Skip to content
Back to search

simulate-skill

MarketplaceWorks with Claude CodeGitHub

The simulate skill for Claude Code: simulation testing with bots, rules and failing tests.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mkhinini-motaz--simulate/badge.svg)](/listings/mkhinini-motaz--simulate)

HTML

<a href="/listings/mkhinini-motaz--simulate"><img src="/api/listings/mkhinini-motaz--simulate/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requirements: Claude Code, and Node 24 or later for the core (the app under test can be in any language, since the bots talk to it over HTTP). The core is tested on Node 25, and `.github/workflows/test.yml` runs Node 24 and 25. The runner sets `NODE_USE_ENV_PROXY` in the app's environment, so a Node app's own `fetch` goes through the egress trap only on a Node that honours that variable.

As a Claude Code plugin, inside a session:

/plugin install simulate --marketplace mkhinini-motaz/simulate

If your Claude Code rejects `--marketplace`, add the marketplace first: `/plugin marketplace add mkhinini-motaz/simulate`, then `/plugin install simulate@simulate-skill`.

Or copy the skill by hand:

git clone https://github.com/mkhinini-motaz/simulate
cp -R simulate/skills/simulate ~/.claude/skills/simulate

The core is ESM TypeScript run by Node, so `sim/` gets its own `package.json` with `{"type":"module"}` and stays out of your `tsconfig`.

Then run `/simulate plan` in your project (an installed plugin may list the skill as `/simulate:simulate`). The skill follows the [Agent Skills](https://agentskills.io) format (`skills/simulate/SKILL.md`), so other agents that read that format can load it too.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines
  1. {
  2. "name": "simulate-skill",
  3. "description": "The simulate skill for Claude Code: simulation testing with bots, rules and failing tests.",
  4. "owner": {
  5. "name": "mkhinini-motaz",
  6. "url": "https://github.com/mkhinini-motaz"
  7. },
  8. "plugins": [
  9. {
  10. "name": "simulate",
  11. "source": "./",
  12. "description": "Simulation testing for Claude Code: bots play your users against an isolated copy of your app, checks enforce the rules you confirm, and every finding becomes a failing test."
  13. }
  14. ]
  15. }
README.md · README · 91 lines
  1. # simulate
  2. A Claude Code skill that builds a simulation of your product and uses it to find bugs. Bots play your users against an isolated copy of your app, and an oracle checks the rules you confirm. A finding counts only when it becomes a failing test in your own test suite.
  3. Status: experimental. It is proven on the demo app in this repo, and it was tried privately on one real multi-sided product: on a commit from before two of its fixed bugs, it re-found both, each confirmed by a failing test. Reports from other projects are welcome as issues.
  4. ## How it works
  5. 1. **Detect.** Claude reads your code and docs: the stack, the start command, the roles, the entities and their states, money fields, and every place that sends SMS, mail, push, payments or webhooks. It lists every feature in `sim/FEATURES.md`: all routes from the framework's own route list, plus scheduled jobs, webhooks, realtime channels, admin screens and locale files.
  6. 2. **Ask.** A fixed set of "must never happen" questions (privacy between users, once means once, totals agree, final is final, nothing waits forever), then only the gaps the code could not answer. At most 7 questions before the plan, and up to 8 more with it, each with a suggested answer.
  7. 3. **Write rules.** `sim/RULES.md` lists each rule with its source. Rules read from the code are marked `observed` and never fail a run until you confirm them, because the code is what is under test.
  8. 4. **Plan.** `sim/PLAN.md` lists the scenarios, checks and isolation, and a coverage table: each feature with its scenarios, and each feature left without one, by name. For a marketplace it also walks a list of 78 cases in 11 areas (dispatch, refunds, scoped admins, privacy, abuse and more). You approve it before any code is written.
  9. 5. **Build.** A fixed safety core is copied into `sim/core/` unchanged. Claude generates only the part specific to your project: how to start the copy, the scenarios and the rules.
  10. 6. **Run and triage.** The summary's second line says how many features the bots reached and lists the routes they never called. Each violation is sorted into a simulator bug, a product bug proven by a failing test, or a known gap.
  11. A project with no docs ends step 3 with some.
  12. ## Modes
  13. | Command | What it does |
  14. |---|---|
  15. | `/simulate plan` | Detect, ask and write the rules and plan. No code. |
  16. | `/simulate every-scenario` | Every scenario once, then triage and report. |
  17. | `/simulate scenario <name>` | One scenario, for one bug or one feature. |
  18. | `/simulate replay <run dir>` | The same seed and scenario as an earlier run. |
  19. After new code, run `/simulate plan` again. It reuses `sim/`: it reads only the files changed since the plan's base commit, compares the route list with `FEATURES.md` to find new and removed routes, keeps every answer you already gave, and plans and builds only the new features. The full `every-scenario` run still checks every older feature, and costs no model tokens.
  20. Not in this version: load, process restarts and other faults, device walks, reviewer rehearsals and nightly runs. Abuse cases are ordinary scenarios.
  21. ## Safety
  22. The core refuses to start, with a reason for each refusal, when:
  23. - the database name (a name, a URL or a SQLite file) does not end in `_sim`, or has `prod`, `live` or `test` as a word in it; or a database host (in the URL, a `?host=`, or `DB_HOST`, `DATABASE_HOST`, `PGHOST`, `MYSQL_HOST`) is not local and you did not list it;
  24. - the environment says production (`NODE_ENV`, `APP_ENV`, `RAILS_ENV` and similar);
  25. - any value looks like a live secret (live payment keys, cloud access keys, tokens, private keys) or names a host you forbid;
  26. - the copy holds a `.env` file anywhere outside `node_modules`, `vendor` and `.git*`.
  27. The same checks run on what your start script adds to the environment.
  28. The app runs with an environment built from an allowlist plus fake values, never your shell's environment. The app gets a fresh `HOME` inside the run folder, so tools that look up `HOME` (most SDKs and CLIs) do not find your `~/.aws`, `~/.netrc` and the like. A process can still find the real home through the user database (`os.userInfo()`, Python `pwd`), so the container is the full wall. List `HOME` in the plan's `allow` only when it must have the real one. Senders write to an outbox file. Outbound HTTP goes through a local trap that refuses it and fails the run. An app that ignores proxy settings is not caught by the trap, so for the strongest wall run the whole simulator (runner, copy and database) in one container with `--network none`. Fake users get example.com emails and fictional phone numbers.
  29. ## Install
  30. Requirements: Claude Code, and Node 24 or later for the core (the app under test can be in any language, since the bots talk to it over HTTP). The core is tested on Node 25, and `.github/workflows/test.yml` runs Node 24 and 25. The runner sets `NODE_USE_ENV_PROXY` in the app's environment, so a Node app's own `fetch` goes through the egress trap only on a Node that honours that variable.
  31. As a Claude Code plugin, inside a session:
  32. ```
  33. /plugin install simulate --marketplace mkhinini-motaz/simulate
  34. ```
  35. If your Claude Code rejects `--marketplace`, add the marketplace first: `/plugin marketplace add mkhinini-motaz/simulate`, then `/plugin install simulate@simulate-skill`.
  36. Or copy the skill by hand:
  37. ```sh
  38. git clone https://github.com/mkhinini-motaz/simulate
  39. cp -R simulate/skills/simulate ~/.claude/skills/simulate
  40. ```
  41. The core is ESM TypeScript run by Node, so `sim/` gets its own `package.json` with `{"type":"module"}` and stays out of your `tsconfig`.
  42. Then run `/simulate plan` in your project (an installed plugin may list the skill as `/simulate:simulate`). The skill follows the [Agent Skills](https://agentskills.io) format (`skills/simulate/SKILL.md`), so other agents that read that format can load it too.
  43. ## Use with other agents
  44. The skill is a `SKILL.md` folder, a format Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode also load. All five read a project's `.agents/skills/` folder, so copying `skills/simulate` there should work. The core still needs Node 24 or later. I have only tested it in Claude Code.
  45. The root `plugin.json` follows the [Agent Plugins](https://github.com/agentplugins/agent-plugins-spec/blob/main/spec/1.1.0.md) standard (1.1.0), so clients that load it can install this as a plugin. The list at https://agent-plugins.org/compatible-clients names Cursor, GitHub Copilot, ChatGPT & Codex, Kiro, Hermes Agent, OpenClaw, Grok Bot, NanoClaw, OpenHands, Perplexity Computer and Google Antigravity. I have not tested it in any of them, since none is installed here. Claude Code keeps using `.claude-plugin/`.
  46. ## The demo
  47. `demo/` is a small marketplace API with six planted bugs, listed in `demo/PLANTED.md`, and the simulator the skill would generate for it in `demo/sim/`.
  48. ```sh
  49. npm test # core tests, plus proof that an every-scenario run finds all six bugs and raises no false alarm once they are fixed
  50. npm run demo # one every-scenario run; see the printed run folder (exits 1: the planted bugs are on)
  51. ```
  52. ## Ideas borrowed
  53. - Replay from a seed: [TigerBeetle VOPR](https://github.com/tigerbeetle/tigerbeetle/blob/main/docs/internals/vopr.md), [FoundationDB simulation testing](https://apple.github.io/foundationdb/testing.html).
  54. - Rules checked after every step: [Hypothesis stateful testing](https://hypothesis.readthedocs.io/en/latest/stateful.html).
  55. - A policy document as the oracle for simulated users: [tau2-bench](https://github.com/sierra-research/tau2-bench).
  56. - A Markdown plan between exploring and running: [Playwright test agents](https://playwright.dev/docs/test-agents).
  57. - Faults and outbound calls trapped at a proxy: [Toxiproxy](https://github.com/Shopify/toxiproxy).
  58. - Related, and a good fit for web walkthroughs: [neonwatty/qa-skills](https://github.com/neonwatty/qa-skills).
  59. ## Contributing
  60. See [CONTRIBUTING.md](CONTRIBUTING.md). Issues labelled [`good first issue`](https://github.com/mkhinini-motaz/simulate/labels/good%20first%20issue) are a good place to start. The easiest help is a field report from your own project.
  61. ## Credits
  62. Built with Claude Code. The lessons in `skills/simulate/references/lessons.md` come from running a simulator of this kind on a real multi-sided product.
  63. ## License
  64. MIT. See `LICENSE`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.