Readme writing
Skill Amey-Thakur/AI-SKILLS/skills/documentation/readme-writing
Plug-and-play skills and prompts for every AI coding agent
npx -y skills add Amey-Thakur/AI-SKILLS --skill readme-writingAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- 19 days oldThe repository was created 19 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
- 4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Write READMEs that deliver value on the first screen, quickstart before reference, and stay maintainable. Use when creating or fixing a project's front-door documentation.
SKILL.md
3.1 KB, as published. Nobody here has run it
README writing
The README is the project's front door, and most readers decide in the first screen whether to continue. Lead with what it is and why they should care, get them to a working state fast, and put reference material where it belongs: below, or elsewhere.
Method
- Answer what/why/for-whom in the first screen. One or two sentences: what this is, the problem it solves, who it is for. A reader landing cold should know in ten seconds whether to keep reading (see landing-page-strategy's five-second test: the README is a landing page for a different audience). Badges and a tagline, not a wall of prose.
- Quickstart before reference. The fastest path to a working result: install, minimal example, expected output (see tutorial-writing's tested-steps rule). A reader wants to see it work before they read the API; front-loading configuration options and architecture buries the moment that earns their investment (see user-activation's time-to-value, docs edition).
- Show, then tell. A concrete runnable example (copy- pasteable, actually tested: see docs-as-code) teaches more than paragraphs of description; lead each capability with what it looks like in use. Abstract feature lists convince nobody; a working snippet does.
- Structure for scanning. Clear headings in a predictable order (what, install, quickstart, usage, configuration, contributing, license), short paragraphs, a table of contents for long ones. Readers scan for their question; a README that must be read linearly to find anything fails the impatient reader, which is all of them (see docs-information-architecture).
- Link out for depth, keep the README lean. Detailed API reference (see api-reference-docs), architecture (see architecture-diagrams), and guides live in linked docs; the README orients and launches, it does not contain everything. A README that tries to be the whole manual becomes the manual nobody reads.
- Include the operational essentials. How to contribute (see onboarding-docs), where to get help, license, and status (maintained? version?): the metadata that tells a reader whether to depend on this. Then keep it current: a README describing an old install command is the first thing that breaks trust (see docs-maintenance).
Boundaries
- The README's job is orientation and quickstart, not comprehensive reference; resist the pressure to document every option there (that is api-reference-docs' job, linked).
- Audience shapes everything: a library README (developers integrating) differs from an application README (users running it) differs from an internal-tool README (the team maintaining it); write for the actual reader.
- A great README over an undocumented codebase is a promise the rest cannot keep; it is the entry point to a documentation system (see docs-information-architecture), not a substitute for one.