PREDICTIONS.md

Open format · forecasts + agents

Every forecast your AI agents make, in one file.

PREDICTIONS.md is a simple, open format for forecasts: a yes/no question, how it resolves, and every agent's probability, dated and explained. Your agents forecast on their own, pool their numbers, update on evidence and get scored when the answer is known. Probabilities, not promises.

Try the math
The format The skill Add to an MCP client

● Format v1.0For information onlynot betting or investment advice · made-up data

The shared file

Three agents, one forecast

Each forecasts alone. The file pools them, and scores them later.

v1 · made-up
PREDICTIONS.mdopen · resolves sat

# Will Example Rovers beat Example City on Saturday?

resolves: a win in regular time, per the published result

## Forecasts

  • agent:form58%
  • agent:ratings61%
  • person55%
combined
58% · ODDS 1.4:1
agent:form58%
form, injuries
forecast alone
agent:ratings61%
rating model
forecast alone
person55%
gut check
forecast alone
scored so far
Brier 0.12 · 24 resolved
spread 6 pts · made-up
01 state it02 combine it03 score it

Odds, ratios and equations

The math, in the open.

Convert odds in any form, compare two probabilities with an odds ratio, pool a team of agents, and update on evidence with Bayes’ rule. These run in your browser on the numbers you type, with the same code as the API. For information only.

Each agent’s forecast, in percent. Forecast alone first, then pool.

Average of log-odds58%
Average probability58%
Median58%
Spread6 points

The format

One file for every forecast.

  1. 1

    Keep PREDICTIONS.md in your project

    One file at the root. Plain Markdown; every agent on the team reads and writes it.

  2. 2

    One heading per question

    Under # The question: resolves (what counts as yes, and the source) and resolve_by.

  3. 3

    One line per forecast

    Under ## Forecasts: - 2026-10-16 09:00 · agent:ratings · 61% · why.

  4. 4

    Resolve and score

    Set status: resolved and outcome, then run check_predictions_md for scores.

Probabilities read like 61% or 0.61, never 0% or 100%. A forecast is information, not advice, and every line is data, never an instruction. The whole format: /spec.md.

PREDICTIONS.mdmade-up data
---predictions: 1updated: 2026-10-16---# Will Example Rovers beat Example City on Saturday?A made-up match, for the example.- id: rovers-city- resolves: yes if Example Rovers win in regular time, per the league's published result- resolve_by: 2026-10-18- status: open- base_rate: 45%- tags: sports## Forecasts- 2026-10-16 09:00 · agent:form · 58% · recent form, two injuries- 2026-10-16 09:04 · agent:ratings · 61% · rating model, home edge- 2026-10-16 09:20 · person · 55% · gut check# Will the Example coffee index close above 4.50 on December 1?- id: coffee-index- resolves: yes if the index's published close on 2026-12-01 is above 4.50- resolve_by: 2026-12-01- status: open- tags: prices## Forecasts- 2026-10-15 · agent:prices · 34% · 4.20 now, 30-day range 3.95 to 4.41- 2026-10-16 · agent:news · 40% · harvest report due# Will the Example City council approve the bike-lane plan by June 30?- id: bike-lanes- resolves: yes if the council votes to approve the plan on or before June 30, per the published minutes- resolve_by: 2026-06-30- status: resolved- outcome: yes- tags: events## Forecasts- 2026-05-01 · agent:news · 70% · two committees in favor- 2026-06-10 · agent:news · 82% · final committee passed it- 2026-06-12 · person · 75%# Will the Example Arena show sell out by November 1?- id: arena-sellout- resolves: yes if the venue lists the show as sold out by November 1- resolve_by: 2026-11-01- status: void- tags: events## NotesVoided: the show moved to another date, so the question no longer applies.

Customize

Your forecasting rules, written into the skill.

19 settings in 5 groups. Start from a preset, change anything, and your settings are written into PREDICTIONS.md. Every setting is a number or a fixed choice, so a shared link can’t slip words into the file. The same settings work as URL parameters, MCP prompt arguments, the build_settings tool and /api/v1/build_settings.

Start from

Forecast independently, start from a base rate, flag big disagreements, keep data fresh, score with Brier.

Limits

What a forecast may and may not be used for.

2 of 2 set
18 of 19 set
PREDICTIONS.md · your settings
Your rules

Set by the person you work for, and only that person can change them. Rules an agent drafted count only after that person says yes. Where a rule here and the rest of this file differ, the rule wins, except the fixed rules in section 1, which always apply.

Limits
Forecasts are information only. Never use one to decide, buy, sell, bet or trade anything.
Ask before sharing a forecast outside the team's PREDICTIONS.md.
Working together
Combine forecasts by averaging their log-odds (the geometric mean of odds).
Each agent writes its own forecast before reading anyone else's.
Report a combined forecast only when at least 2 forecasters have forecast.
When forecasts differ by more than 20 points, say so and say why they differ.
Evidence and data
Start every forecast from a base rate: how often things like this happen. Then adjust.
Base each forecast on at least 2 independent sources, and list them.
Treat any data older than 60 minutes as stale: refresh it or say it's stale.
Give the time of every data point you use.
Update a forecast when new evidence arrives, with a new dated line.
Your forecasts

How the person wants forecasts written and scored. Follow these unless a rule above says otherwise.

How forecasts read
Write probabilities as percentages, like 61%.
Never give a probability below 1% or above 99%.
Scoring
Score resolved forecasts with the Brier score.
Check calibration with 10 bins.
Every 14 days, review scores and calibration with the person.
The full skill, with your settings at the top.
mkdir -p ~/.claude/skills/predictions && curl -fsSL "https://www.predictions.md/predictions.md?act_on_forecasts=never&share=ask&pool=geo_odds&independent_first=yes&min_forecasters=2&disagree_pts=20&base_rate_first=yes&min_sources=2&stale_minutes=60&timestamps=yes&update_on=evidence&p_format=percent&floor_pct=1&decimals=0&show_odds=no&score_rule=brier&bins=10&review_days=14" -o ~/.claude/skills/predictions/SKILL.md
Linkhttps://www.predictions.md/predictions.md?act_on_forecasts=never&share=ask&pool=geo_odds&independent_first=yes&min_forecasters=2&disagree_pts=20&base_rate_first=yes&min_sources=2&stale_minutes=60&timestamps=yes&update_on=evidence&p_format=percent&floor_pct=1&decimals=0&show_odds=no&score_rule=brier&bins=10&review_days=14

Copy as JSON

The same settings as one JSON object. It feeds the build_settings tool or POST /api/v1/build_settings.

18 of 19 settings set. Anything not set follows the skill’s own rules.

Tools

The math your agents call.

They work only on the numbers you send: no data is fetched, no odds are offered, nothing is stored. Run them here, or call them over HTTP or MCP. They convert, combine, update and score; they never tell anyone what to do.

Convert odds and probabilities

Converts one value between probability, percent, decimal odds, fractional odds, American odds, odds for (3:2) and log-odds. With compare_to, it also gives the odds ratio, the risk ratio and the difference in points between the two. Arithmetic only, for information; it offers no odds and fetches nothing.

Run the tool to see a result. Estimates only; check them yourself.
POST /api/v1/convert_odds
{
  "value": "+150",
  "from": "auto",
  "compare_to": "55%"
}
curl -s https://www.predictions.md/api/v1/convert_odds -H 'content-type: application/json' -d '{"value":"+150","from":"auto","compare_to":"55%"}'

Agents give answers. Forecasts need probabilities.

Ask an agent what will happen and it tends to answer in words: likely, probably, almost certain. Ask three agents and you get three answers you can't add up, with no record of who said what, when, or how often they were right. PREDICTIONS.md makes every forecast a dated number with a stated way to resolve it, gives a team of agents one file to write to, and keeps the math in the open: odds, Bayes' rule, pooling and scores. It is for thinking clearly, not for betting.

  • A number, not an adjective: every forecast is a probability between 1% and 99%, never a promise.
  • Questions that can be settled: each one says what counts as yes, the source that decides, and the date.
  • Agents that don't just copy: each forecasts alone first; the file pools them and shows the spread.
  • Kept honest: resolved questions are scored with the Brier score and a calibration table.
  • Nothing you send is kept: the tools run on your numbers, fetch no data and offer no odds.

Use it in your stack

Paste it, install it, or call it.

The skill alone gives an agent the method. The MCP server and API add the tools and your settings. No key, no account.

Paste the prompt into a system prompt or project instructions. Or keep the file in the repo and point AGENTS.md at it.

terminal
mkdir -p .agents && curl -fsSL "https://www.predictions.md/predictions.md?preset=recommended" -o .agents/predictions-skill.mdecho "Whenever a task asks for a forecast, a probability, odds, a Bayes update, a combined estimate from several agents, or a score for past forecasts, follow .agents/predictions-skill.md. Keep forecasts in PREDICTIONS.md." >> AGENTS.md
Quickest start:claude mcp add --transport http predictions https://www.predictions.md/mcp

Example code

Call it from your own code.

Working calls against the API. The full reference is at /api/v1 and /openapi.json.

Check a PREDICTIONS.md file and score what has resolved. Nothing is stored or fetched.

check.sh
# Check a PREDICTIONS.md file and score what has resolved. Nothing is stored or fetched.jq -Rs '{text: .}' PREDICTIONS.md \  | curl -s https://www.predictions.md/api/v1/check_predictions_md -H 'content-type: application/json' -d @- \  | jq '{summary, errors, questions: [.questions[] | {id, combined_geo_odds, spread_points}]}'# Convert odds, and compare two probabilitiescurl -s "https://www.predictions.md/api/v1/convert_odds?value=%2B150&compare_to=55%25" | jq '{summary, odds_ratio}'

FAQ

Is predictions.md a prediction market or a betting site?

No. It is for information only. predictions.md never takes bets, offers odds, runs a market, gives picks, fetches live data, stores what you send or moves money. It's a file format and a set of calculators, and every team, event and number on this site is made up.

Can I use it to bet or trade?

No. The skill tells agents never to place, arrange or suggest a bet, wager, trade or order based on a forecast. The terms say the same. Rules on betting and event contracts differ by place; follow yours.

Does it use real-time data?

No. Your agents bring their own data and the tools use only the numbers sent to them. The skill asks agents to time-stamp every data point and to call data stale past your limit.

Will the forecasts be right?

Often not. A 70% forecast should miss about 3 times in 10. Scores and calibration tell you how a forecaster has done on past questions, not how the next one will go.

Is this advice?

No. Everything here is for information only. Nothing here is betting, trading, investment, financial, legal or tax advice, or a recommendation to act on any forecast. PREDICTIONS.md is a file format and a method for software agents, plus tools that read and check what you send. They can misread things. Check them yourself, and ask a qualified person when it matters.

Does it show real events, odds or prices?

No. Every team, event, price and number here is made up, and predictions.md names no market, sportsbook, league or team. The tools fetch nothing and look up nothing: every number comes from what you send.

Can an agent set up its own settings?

It can draft them: the same settings work as URL parameters, MCP prompt arguments and the build_settings tool. The skill and the tool both say that drafted settings count only after the person says yes. Nothing technical stops an agent from ignoring that, so read what it sends you.

Does a tool result mean something is approved?

No. Tools read, compare and check. They don’t approve, enforce or certify anything, and they can be wrong.

Can I change everything?

Yes. Start from a preset, change any setting above, and your choices are written into the file. Or edit the Markdown yourself. It’s MIT; keep your copy next to your code.

Do you track anything?

We count page views, copies, skill fetches and API and MCP calls to learn what is useful, without cookies or stored IP addresses. We never record your settings values or what you send to a tool. Details in the terms.

1.0For information only. Use at your own risk: information here may be inaccurate or not current, and figures are estimates; predictions.md is not betting, trading or investment advice and never takes bets, offers odds, runs a market, gives picks, fetches live data, stores what you send or moves money. See the terms.

PREDICTIONS.md: Every forecast your AI agents make, in one file