Instructions Writer: READMEs That Work on the First Try

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.