readme-rework
Skill2 starsChanged 22 days agoMITView on GitHub
Use before a houserules release, or when the README needs rework: an independent discovery of what houserules is, first-time-reader personas, and a best-practice rewrite, scaled to a major, minor, or patch release
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- template/AGENTS.mdAGENTS.md
- tests/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- template/CLAUDE.mdCLAUDE.md
- designingSkill
- finishing-a-featureSkill
- houserules-stepSkill
- migrating-knowledgeSkill
- orchestratingSkill
- planningSkill
- project-knowledgeSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Before each release, the README gets the rework that the release calls for.
- Distinctive: line 17
Every command the README shows runs at the release head with its real output, through the README tests.
- Very specific: line 19
Keep every brief, report, and design note in the batch workspace, with the prefix readme-.
- Distinctive: line 27
Persona round 2: Run the same personas on the new README.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
The README rework at a release
Before each release, the README gets the rework that the release calls for. The steps come from the 2.0.0 rework (design.md 285 to 288). The briefs and the persona catalog are beside this file.
Rules for every run
- The README follows the practice of open-source READMEs: a short description, install, usage with real output, the features in brief, concepts, documentation links, contributing, and the license last. Read the current guidance at each major run: GitHub Docs: About the repository README file, the standard-readme spec, and Make a README.
- Every houserules term the README uses is explained in plain words where it first appears and links to its entry in the README's short glossary. A picture replaces a wall of text where it shows the mechanism better: the core loop, what
initwrites, the optional layers, the review flow (design.md 290). - The persona reports are evidence of where a first-time reader gets lost. Fix those places inside the structure above. Do not add a section, box, or heading for a persona, and do not address a reader type (design.md 286).
- Readers and the discovery agent are general-purpose agents, not the implementer or reviewer templates of this repository: those load houserules knowledge. A persona reads only a frozen copy of the README and researches nothing.
- The discovery agent never reads the README or a review of it. It learns houserules from the code, the files, and the binary (design.md 287).
- Every command the README shows runs at the release head with its real output, through the README tests.
- The owner reviews the README before the release.
- Keep every brief, report, and design note in the batch workspace, with the prefix
readme-.
The steps
- Discovery. Make a detached worktree of the release head. Remove
README.mdand every test that quotes it from its working tree. Build the binary at that head. Dispatch one agent withdiscovery-brief.md. It writes what houserules is, by capability, with commands and output. - Persona round 1. Freeze a copy of the current README outside the repository. Dispatch one agent per chosen persona of
personas.md, withpersona-brief.mdand its persona text. The personas run in parallel. - Findings and design. Merge the reports into one list: the findings that many personas share, then the findings of each. Write the target structure from the practice above. The frame (the description, usage, feature overview, and glossary) comes from the discovery report and the tree, not from the old README.
- Rewrite. Dispatch an implementer with the findings and design. Reference material moves whole to pages under
docs/, with its runnable blocks and tests. The short description equals thedescriptionofcrates/houserules/Cargo.toml. Review the task as any other. - Persona round 2. Run the same personas on the new README. Compare each decision and each top change with round 1. Fix what is still unclear, then take the README to the owner.
How much to run
| Release | Discovery | Personas | Rewrite |
| Major | Yes. | Every persona of the catalog, in both rounds. | The whole README, reframed from the discovery report. |
| Minor | Only when the release adds or removes a capability that changes what houserules is, or the first screen no longer states what the release does. | The personas whose capabilities the release changes, and persona 13 when install, init, or the quick start changed. Both rounds. | The sections of the changed capabilities, the first screen if it changed, and the links to new docs pages. |
| Patch | No. | Persona 13 only, when an install step or a quick-start command changed. One round. | Only the facts the release made stale. |
To find the capabilities that a release changes, read its commits since the last tag (git log v<last>..HEAD --format=%s) and its CHANGELOG.md section. Match each change to the capabilities column of the catalog. Add a persona to the catalog when a release adds a capability that no persona exercises.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

