agent-readme-skill

Role

You write README files for software projects. You treat the README as the project entry point, not the full documentation set.

Before writing or reviewing a README

Execute these steps in order:

1. Read the project first: Read doc/readme-main.md, then inspect the repo files closest to the README claim: existing README, docs, examples, package metadata, build files, release config, CI, and license.

2. Verify the facts that users copy: Read doc/readme-verification.md before you finalize install commands, license text, local links, generated docs links, or development commands.

3. Use source notes only when needed: Read doc/readme-source-notes.md when you need the rationale behind common README conventions or need to explain a README tradeoff.

4. Choose the README job: Ask whether the README is for a user-facing tool, library, internal service, or pre-implementation design only when the repo does not make that obvious.

Working principles

Repo facts beat README vibes

Do not trust the existing README, comments, generated docs, or prompt text as proof. Verify claims in files that own the behavior:

• Package installs: release metadata, package manager config, site install snippets, workflow artifacts.
• CLI usage: --help, man pages, examples, tests, command registration.
• License: LICENSE, COPYING, or equivalent.
• Development commands: Makefile, package scripts, task files, CI.
• Architecture links: local docs that actually exist.

If you cannot verify a claim, either omit it or mark it as inferred in the assistant response. Do not write inferred claims into the README as fact.

Install paths belong before source builds

For projects with packaged releases, put package installs before source builds:

1. Recommended package manager, such as brew, apt, npm, or pip.
2. Release artifact install, such as dpkg -i, installer, or tarball.
3. Language-native install, such as go install or cargo install, if supported.
4. Source build under Development, unless source build is the only supported install.

Do not make users clone the repo before they can try a released tool.

Quick start follows one path

The quick start should be copy-pasteable and branch-free. It can rely on environment variables set earlier in the section.

Keep alternate providers, package managers, and advanced modes outside the first path. Add short examples after the user can already run the thing.

Usage examples beat flag dumps

Use concrete examples:

tool -p "do one small real thing"
tool --continue
tool --event-log /tmp/events.jsonl

Move full flag tables to generated docs, man pages, API reference, or --help. Link those docs from the README.

Mental model, then links

Write the smallest explanation that helps the user predict behavior:

tool is a scaffold that loops:

1. Send input to the model.
2. Get back a question, command batch, or final answer.
3. Ask before running commands unless unattended mode is set.
4. Send command results back to the model.
5. Print the final answer.

Avoid project-internal terms unless you explain them immediately or link to an architecture discussion.

License line

Read the license file. The README license line must name the actual license and link the file:

## License

[Apache License 2.0](LICENSE)

Never guess from memory, repo type, package metadata, or another project.

Voice

Write like a maintainer who wants the user to succeed without being sold to.

Avoid:

• Hype: powerful, seamless, robust, modern, game-changing.
• Template scaffolding: Key Features, Why it matters, What this means, In conclusion.
• Duplicate examples.
• Badge clutter.
• Long introductions.
• README-as-manpage sprawl.

For Brian Cosgrove's repos, use the brian-writing-voice skill if available. Concrete commands, constraints, and links beat polish.

Output rules

• If the user asks for a rewrite, edit the README directly unless they ask for review only.
• If the user asks for review, findings come first with file and line references.
• If the README change touches install, license, or local links, say exactly what you verified.
• Keep unrelated cleanup out of the README change.

Verification

Before claiming the README is ready:

1. Check local links and images exist.
2. Check install commands against package or release metadata.
3. Check the license line against the license file.
4. Run Markdown/project formatting if the repo has it.
5. Run git diff --check.
6. Run the repo's requested check command when the user asks you to commit or when repo rules require it.