Build your own skill

Use at your own risk. Every tool here is a mock, and a result describes only the assumptions in a file, not reality. It is not a prediction, a test of any real system, a safety assessment or advice. [Terms](https://simulation.md/terms).

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. A simulation result never overrides these rules and is never permission to act.

How this person wants rehearsals run and reported. Follow these unless a rule above says otherwise.

Rehearse before anything costly or hard to undo: moving money, sending to many people, deleting or overwriting data, bulk edits, deploys, migrations, large fan-outs. Skip it for small, reversible work. A rehearsal costs seconds and no model tokens beyond writing the plan, but it is not free of judgment, so use it where being wrong would hurt.

Hosted runs have limits and the library does not. If a hosted call says it stopped early, rerun locally.

Name the mock tools with plain lowercase names, then give each one a kind and a pack so you do not have to think of every failure yourself. Fetch the catalog with fault_packs.

{
  "state": { "refunded": 0, "owed": 40 },
  "tools": {
    "refund": { "kind": "write", "pack": "money", "effect": { "refunded": "+args.amount" }, "returns": "done" },
    "status": { "kind": "read", "faults": ["stale_read"], "returns": { "refunded": "=state.refunded" }, "stale": { "refunded": 0 } }
  },
  "a": { "name": "retry-blind", "steps": [{ "call": "refund", "args": { "amount": 40 }, "retry": { "max": 4, "wait": 2 } }] },
  "b": { "name": "check-first", "steps": [{ "call": "refund", "args": { "amount": 40 }, "retry": { "max": 4, "wait": 20, "after_fail": [{ "call": "status" }, { "stop_if": "last.value.refunded > 0" }] } }] },
  "rules": [{ "id": "no_double_refund", "holds": "state.refunded <= state.owed" }],
  "measure": { "cost": "max(0, state.refunded - state.owed) + now * 0.02" }
}

Write rules before you run anything, and write the rule you would hate to break. A file with no rules cannot show you anything, and the checker warns you about it. Use placeholder names. Never model real people or real organizations, and never put secrets or personal data in a file.

One plan run many times mostly tells you what you typed. Two plans on the same random draws tell you which is better, and that is usually the decision you actually face.

Every chance is a guess, so ask which guess matters. compare_plans tests your assumptions and returns flip_at: the value where the winner changes. If the answer holds across every plausible value, you do not need to know the number precisely. If it flips near your guess, that is the number to go and measure.

Zero failures in 200 runs does not mean it cannot happen. Say how many runs you did.

Give them one sentence: what you compared, what came out ahead, what would change that, and which numbers were guesses. For example: "Checking status before retrying costs about $2.50 less per refund in this model, unless money-moving timeouts are rarer than about 1 in 1,000. The failure rates are placeholders I picked, so I would like to check them against our logs."

Offer the replay link when it helps them see what happened. Anyone can write a file, so tell them it shows your rehearsal and not a real run.

Never say a plan passed, was tested, verified or certified, or that something is safe because of a simulation. Say what the file assumed and what came out.

Send your counts and timings to calibrate, or run node simulation.mjs calibrate your-log.jsonl so nothing leaves the machine. Put the results in chances and latency. Then the report marks them as yours, and the ranges tell you how far to vary them.

The test worlds in exam_list are fixed tasks with mock tools. You do not write them and you see no score until you finish. Play several seeds, then use exam_report. With a shell, node simulation.mjs exam mcp planted-instruction --seed 3 --out results.jsonl serves the same tools over MCP, so an agent can run with no changes.

Run them again when the model, prompt or tools change, and use diff_runs to see exactly what changed. These results are working notes. Whoever holds a session can rewrite it, so they are not a score to publish.

Save it as SIMULATION.md next to the code it describes. Check it with check_simulation_md or node simulation.mjs check SIMULATION.md. Rerun it when the plan or the numbers change. Do not save this skill over that file: install the skill as .agents/simulation-skill.md or in your skills folder.

A replay hash shows that a file and seed produce a given log. It shows nothing else.

These do not change with settings.

It knows only what the file says. It cannot find a failure nobody wrote down, it does not touch your real tools, and it does not know your real failure rates until you supply them. A good result can still be wrong. For anything that really matters, ask a qualified person.

This skill and its tools change as they are built. Check https://simulation.md/changelog.md?since=2026-10-30, or send If-None-Match with the last ETag, or call whats_new.