How do I install the Write Readme skill?

Run npx skillmds@latest add linnene/write-readme in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Write Readme safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Write Readme?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Write Readme free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Write Readme?

linnene (@linnene) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Write Readme by linnene — Agent Skill

Name: Write Readme
Author: linnene

Write Readme

Create or update a README.md for a module, feature, or the project root. Use when the user says 'write a README', 'update the docs', 'document this module', 'add a getting started guide'. Don't use for architecture decisions — use write-adr. Don't use for user stories — use write-spec.

linnene ca33a84 3.0 KB Updated Sep 17, 2026

File contents

Write README

Instructions

- Determine the scope: project root (README.md) or specific module (src/{module}/README.md).
- Read AGENTS.md to extract the project's semantic commands (dev, test, build, lint).
- Write the README with these sections:
- One-paragraph description — what this project/module does, in plain language.
- How to run — dev, test, build commands. Use the semantic commands from AGENTS.md, not raw tool commands.
- Architecture overview — brief summary with links to docs/specs/ for details.
- Key decisions — link to relevant ADRs in docs/specs/adr/.
- Keep it concise — link to detailed docs instead of duplicating content.
- If updating an existing README, preserve any custom sections the user has added.
- Verify all links resolve to existing files.

Critical

README must be self-sufficient for a new developer — they should be able to clone, install, and run within 5 minutes following only the README.
Use semantic commands from AGENTS.md (e.g., npm run dev) not tool-specific commands (e.g., npx ts-node src/index.ts) — semantic commands survive tooling changes.
Never duplicate content that lives in docs/specs/ — link to it instead. Duplicated content drifts and confuses.
Keep the README under 200 lines — longer READMEs don't get read.

Examples

User says: "Write a README for the billing module."

Actions:

Scope: module → src/billing/README.md.
Read AGENTS.md → commands are npm run dev, npm test, npm run build.
Write:
- Description: "Billing module handles invoice generation, payment processing, and subscription management."
- How to run: npm run dev, npm test -- --filter billing.
- Architecture: link to docs/specs/billing/domain-model.md.
- Key decisions: link to docs/specs/adr/ADR-003-stripe-integration.md.
Total: ~60 lines.

Result: src/billing/README.md created with 4 sections, all links verified.

Troubleshooting

Stale commands → README shows commands that don't work → Re-read AGENTS.md and package.json (or equivalent) to verify current commands before writing.

Missing architecture docs → No docs/specs/ content to link to → Write the README with a placeholder link and note: "Architecture docs pending — see write-spec skill."

README too long → Exceeded 200 lines → Extract detailed sections into docs/ files and replace with links. The README is an index, not an encyclopedia.

---name: write-readmedescription: Create or update a README.md for a module, feature, or the project root. Use when the user says 'write a README', 'update the docs', 'document this module', 'add a getting started guide'. Don't use for architecture decisions — use write-adr. Don't use for user stories — use write-spec.---# Write README## Instructions1. - [ ] Determine the scope: project root (`README.md`) or specific module (`src/{module}/README.md`).2. - [ ] Read `AGENTS.md` to extract the project's semantic commands (dev, test, build, lint).3. - [ ] Write the README with these sections: - **One-paragraph description** — what this project/module does, in plain language. - **How to run** — dev, test, build commands. Use the semantic commands from `AGENTS.md`, not raw tool commands. - **Architecture overview** — brief summary with links to `docs/specs/` for details. - **Key decisions** — link to relevant ADRs in `docs/specs/adr/`.4. - [ ] Keep it concise — link to detailed docs instead of duplicating content.5. - [ ] If updating an existing README, preserve any custom sections the user has added.6. - [ ] Verify all links resolve to existing files.## Critical- README must be self-sufficient for a new developer — they should be able to clone, install, and run within 5 minutes following only the README.- Use semantic commands from `AGENTS.md` (e.g., `npm run dev`) not tool-specific commands (e.g., `npx ts-node src/index.ts`) — semantic commands survive tooling changes.- Never duplicate content that lives in `docs/specs/` — link to it instead. Duplicated content drifts and confuses.- Keep the README under 200 lines — longer READMEs don't get read.## Examples**User says:** "Write a README for the billing module."**Actions:**1. Scope: module → `src/billing/README.md`.2. Read `AGENTS.md` → commands are `npm run dev`, `npm test`, `npm run build`.3. Write: - Description: "Billing module handles invoice generation, payment processing, and subscription management." - How to run: `npm run dev`, `npm test -- --filter billing`. - Architecture: link to `docs/specs/billing/domain-model.md`. - Key decisions: link to `docs/specs/adr/ADR-003-stripe-integration.md`.4. Total: ~60 lines.**Result:** `src/billing/README.md` created with 4 sections, all links verified.## Troubleshooting**Stale commands** → README shows commands that don't work → Re-read `AGENTS.md` and `package.json` (or equivalent) to verify current commands before writing.**Missing architecture docs** → No `docs/specs/` content to link to → Write the README with a placeholder link and note: "Architecture docs pending — see write-spec skill."**README too long** → Exceeded 200 lines → Extract detailed sections into `docs/` files and replace with links. The README is an index, not an encyclopedia.## See also- `write-adr` — for recording architectural decisions- `write-spec` — for user stories with acceptance criteria

Frequently asked questions