- Home
- Skills
- Writing & Content
- Instructions Writer: READMEs That Work on the First Try
More screenshots
Works with the AI Agents you already use
Instructions Writer: READMEs That Work on the First Try
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
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.txtlists 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.jsonhas to be copied fromconfig.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.tomlorenvironment.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 methodreferences/: 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 formatexamples/: 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
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
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 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
Permissions
File Scopes
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.