| name | readme-generator |
| description | Use when creating, rewriting, or updating a repository's README, the user-facing capture of a project's intent. Route reference documentation, changelogs, contributing guides, and agent instruction files to their own tasks. |
README Generator
Job In Hand
Name which job this invocation is before shaping any output:
- Create: derive the README from a fresh reading of the repository.
- Maintain: check the existing README's claims against the repository's current state and change
only what no longer holds.
When the request does not settle the job, the presence and state of an existing README usually does.
Ask only when neither does.
Read the Repository
Recover two things from repository facts (manifests, source layout, documentation, history) before
drafting a line:
- Repo type: the kind of artifact the repository delivers. The type fixes who the reader is and
what the README must sell. A library sells a capability and the path to adopting it; an executable
sells an outcome and the path to running it; a thesis or research repository sells a claim and the
path to engaging with it. Identify the type from evidence; when the evidence is genuinely mixed,
ask the requester rather than blending shapes.
- Intent: the problem the project exists to solve or the claim it makes, in the project's own
terms. A README captures intent. It describes mechanism only where mechanism is what the reader is
deciding to adopt. When intent cannot be grounded in repository facts, ask the human who owns the
project; do not invent it.
Shape the Arc
Arrange content as a rough arc, not a template: a one-line description, a hook that earns the
reader's next minute, progressively deeper detail, and disclosures at the end (status, limitations,
licence, attribution). The repo type decides which stations on the arc exist and how deep each goes.
Drop any station the project does not need, and reorder when the project reads better another way.
Write
Write for the reader the repo type names, in a register that markets honestly: the hook sells what
the project actually does, and every claim in the file traces to a repository fact or a recorded
requester answer. Use HTML inside the Markdown (alignment, banners, badges, collapsible sections)
where it improves the look and feel; presentation carries the content, never replaces it. Target
GitHub-flavoured Markdown unless the repository's host says otherwise, and keep anything beyond
plain Markdown inside what that host renders.
Maintain
Let the request set the reading scope. When it localises the drift, read the repository state the
touched claims depend on and leave the rest of the file alone. Walk the full README claim by claim,
against a fresh reading of the repository, only when the request is about overall staleness or does
not say where the drift is. Update claims the project has outgrown, keep voice and structure that
still serve the intent, and surface rather than silently rewrite any change that alters what the
project claims to be. Drift in fact is yours to fix; drift in intent is the requester's call.
Present
Hand over the README with the repo type identified, the intent recovered and where it was grounded,
and any claim resting on an assumption instead of a repository fact.
