agentleFS
jblosseyjblossey/houserules/.claude/skills/readme-rework/SKILL.md

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

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
  1. Distinctive:

    Before each release, the README gets the rework that the release calls for.

    line 8
  2. Distinctive:

    Every command the README shows runs at the release head with its real output, through the README tests.

    line 17
  3. Very specific:

    Keep every brief, report, and design note in the batch workspace, with the prefix readme-.

    line 19
  4. Distinctive:

    Persona round 2: Run the same personas on the new README.

    line 27

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 init writes, 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

  1. Discovery. Make a detached worktree of the release head. Remove README.md and every test that quotes it from its working tree. Build the binary at that head. Dispatch one agent with discovery-brief.md. It writes what houserules is, by capability, with commands and output.
  2. Persona round 1. Freeze a copy of the current README outside the repository. Dispatch one agent per chosen persona of personas.md, with persona-brief.md and its persona text. The personas run in parallel.
  3. 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.
  4. 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 the description of crates/houserules/Cargo.toml. Review the task as any other.
  5. 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

ReleaseDiscoveryPersonasRewrite
MajorYes.Every persona of the catalog, in both rounds.The whole README, reframed from the discovery report.
MinorOnly 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.
PatchNo.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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.