More screenshots

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    Instructions Writer: READMEs That Work on the First Try

    1

    Your agent rewrites a README, setup guide, reproduction steps or lab protocol from the facts in your project, then has a fresh agent follow it to the letter in a clean copy and fixes every step it had to guess.

    $5

    Secure checkout via Stripe

    Money-back guarantee

    Converts to your local currency at checkout

    Security scanned
    Instructions Writer: READMEs That Work on the First Try

    Instructions Writer: READMEs That Work on the First Try

    Example session with this skill installed

    Our README is a mess: a new student in the group spent a day trying to get Figure 2 out of this repo. Rewrite README.md so someone with a fresh clone can set up, reproduce Figure 2 and run the tests, and test it before you give it back to me.

    • Read your context and instructions
    • Compiled the instructions writer

    I've rewritten README.md and tested it. A fresh agent that saw only the new README and a clean copy of the repo set it up, reproduced Figure 2 and ran the tests on the first try. Every number and file the README promises matched exactly.

    Why the old README failed. I gave the old README to a separate fresh agent. It failed four times in a row before producing anything:

    • requirements.txt lists only numpy, so the figure script failed for lack of matplotlib, and pytest was never installed.
    • It told you to make the figures before the trends, but the figure script needs results/trend.json, which the trend script writes.
    • It never mentioned that config.json has to be copied from config.example.json.
    • It said cd analysis, but the scripts only work when run from the repository root.

    What the new README has: a setup section with a virtual environment and the config step; "Reproduce Figure 2" in the right order with the expected output (mean trend +0.285 °C/decade, 95% CI +0.206 to +0.372); "Run the tests" ending in 2 passed; a table of which command produces which result; and troubleshooting entries for the errors a newcomer will actually see.

    Needs you: the repository URL is a <TODO> in setup step 1, and there is a <TODO> to confirm the numbers match the published Figure 2.

    Code changes I'd recommend (not made): add matplotlib and pytest to requirements.txt; stop clean.py overwriting the raw data.

    The test report is in instructions-test-README-2026-10-19.md, and the old README is saved as README.orig.md.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    What it does

    The author of a README can't test it: they fill every gap from memory, and the file a missing step would create already exists on their machine. So the new student spends a day on cd analysis, a config file nobody mentioned and a figure script that has to run second. This skill makes your agent write instructions the way you'd write code: from the real project, with each step checkable, then tested.

    • Facts from the project, not from memory. Versions from pyproject.toml or environment.yml, dependencies from the imports actually used, options from the scripts' argument parsers, run order from which script writes which file, data location from the config. Contradictions with the old text are listed; anything the project can't answer stays a visible <TODO>, never an invented value.
    • Steps you can check. Every task has its time, the folder to run from and what you need; numbered, copy-pastable commands, one per block; the output to expect after each; the likely error right next to the step that causes it; and a final check such as a value with its tolerance.
    • A "Reproducing the results" table for research code: each figure, table or headline number with its command, output file, expected value and run time.
    • Tested by a fresh follower. A subagent that sees only the text and a clean copy of the project (no environment, no outputs, no filled-in config) runs every step it safely can and records each error and guess. The agent fixes the text and retests with a new follower, up to three rounds.
    • A test report with what the old text broke, the contradictions found, what was verified by running and what was judged for clarity only, open issues, and code changes it recommends but doesn't make.

    What a run looks like

    In our demo the agent got a synthetic lake-temperature analysis repo with a README written the way real ones are. Run by a fresh follower, the old README failed four times before producing any output: matplotlib never installed, the wrong working folder, a config file never mentioned, and the figure script run before the script it depends on. With the rewrite, a new follower reached Figure 2 and passing tests on the first try, and every promised value matched.

    Protocols too

    For wet-lab and field protocols nothing is executed: the follower walks through as a new lab member and flags missing quantities and units, unsettled choices, warnings that come after the step, and where it is safe to pause.

    What's included

    • SKILL.md: the eight-step method
    • references/: writing rules (with research-specific ones for data, seeds, expected values and run time), the follower prompts for run-throughs and walk-throughs, and the test report format
    • examples/: the demo's before README, after README and test report

    Part of the Aurora Lab research pipeline

    Works on its own, on any project. Pairs well with Aurora Lab's Research Software, which makes the code itself correct and reproducible, and Citable Python Packages (free); neither is needed.

    A follower is a simulated newcomer: it knows more and gives up later than a real one, so for high-stakes instructions a real newcomer is still the final test. Tests run on the agent's own machine, so other operating systems and Python versions are untested; the report states the platform. Steps that need credentials, money, a cluster, large downloads or more than about ten minutes are judged for clarity only, never run, and the report marks them. Without subagents or a fresh session the test happens in a context that knows the project, which makes it less strict; the report says so. Facts the project cannot answer (a repository URL, published values, a licence) stay as visible TODOs for you. Protocols are walked through, not performed: it finds gaps in the text, not errors in the chemistry. It recommends code fixes but doesn't make them unless you ask. Each follower is a separate agent run, so testing costs several times the tokens of a plain rewrite.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before any payment.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Money-back guarantee

    Doesn't do what its page promises? You get your money back.

    Trust & safety

    Security scan

    Security scan passed 29 days ago

    Requires

    Terminal access
    Python
    Git

    Permissions

    Read Files
    Write Files
    Network Access
    Terminal / Shell

    File Scopes

    docs/**
    **/*.md
    pyproject.toml
    requirements*.txt
    environment.yml
    **/*.py
    research/reviews/**

    Reads the instructions you point to and the project files that hold the facts (dependency files, scripts and their options, configuration templates); never reads credentials or .env files. Writes the new or fixed document where you say (keeping the old one as <name>.orig.md when the folder is not under version control) and one test report, in research/reviews/ when a research/ folder exists, otherwise next to the document. Terminal: copies the project into a new folder in the system temp directory and runs the instructions there, deleting it at the end. Network: only when the instructions being tested install packages, and only into an environment inside that temporary copy. Nothing that needs credentials, money, a cluster, a large download or more than about ten minutes is run. Never changes your code or data unless you ask.

    Listed29 days ago

    What's inside

    Frequently Asked Questions

    Any agent that loads SKILL.md skills, including Claude Code, Codex CLI, Cursor and Gemini CLI. It needs a terminal to run the instructions it tests, and works best where the agent can run subagents or start a fresh session, so the follower knows nothing about your project. Where it can't, the agent follows the text itself in a separate pass and says so in the report.

    It runs your instructions, as written, in a temporary copy of the project in the system temp directory, and deletes the copy at the end. Packages are installed only into an environment inside that copy. Anything that needs credentials, spends money, submits cluster jobs, downloads a lot or runs longer than about ten minutes is not run: it is judged for clarity and marked in the report.

    No. It writes the document and the test report. When the code is the problem (a dependency missing from requirements.txt, a script that overwrites raw data), it documents the workaround and lists the fix as a recommendation. It changes code only if you ask.

    Long and GPU steps are not run. The instructions get their run time and hardware written down, plus a quick variant (a subset, a smaller grid) when your project has one, and the follower runs that instead. The report says which steps were verified by running and which were only read.

    Yes, as a walk-through: nothing is executed. The follower reads as a new lab member and flags missing quantities and units, choices the text doesn't settle, hazard warnings that come after the step, and where it is safe to pause. It finds gaps in the text, not errors in the science.

    Yes. It takes versions and dependencies from whatever the project uses (DESCRIPTION, Project.toml, environment.yml, a Makefile) and the follower runs whatever the instructions say. Our demo was a Python repository.

    In our demo, reading the project, rewriting the README and three follower runs (old text, new text, revised text) took about five minutes. Each follower is a separate agent run, so a test uses several times the tokens of a plain rewrite.

    Research Software makes the code correct, tested and reproducible; Instructions Writer makes the README and setup steps work for someone who has never seen the project. They pair well, and neither needs the other.

    New in Writing & Content