readme-writer

name

readme-writer

description

Create, update, or improve README files for any software project. Use this skill whenever the user asks to write a README, update an existing one, improve or fix a README, add documentation to a project, or make a repo "look good on GitHub". Also trigger for: "my README sucks", "add a README", "document my project", "README is out of date", "make my repo more discoverable", "add install instructions", "write docs for my project". The skill reads the actual codebase before writing anything, produces READMEs that match the project type, and knows the difference between a library, a CLI tool, a web app, a Claude Code skill, and a script collection.

README Writer

A good README answers three questions in under 30 seconds: what does this do, why should I care, and how do I start using it. Everything else is secondary. The biggest mistake in README writing is treating it like documentation — it's actually closer to a landing page.

---

Step 1 — Read before writing

Before touching the README, understand the project:

• Read the existing README if there is one
• Read the main entry point (package.json, pyproject.toml, Cargo.toml, SKILL.md, etc.)
• Scan the directory structure — what kind of project is this?
• Check if there's an existing description in package.json, pyproject.toml, or git remote

This prevents the #1 README failure: writing generic content that doesn't match what the code actually does. Two minutes of reading saves ten minutes of rewriting.

---

Step 2 — Identify the project type

The right README structure depends on what the project is. Pick the closest match:

CLI tool — users install it and run commands. Needs: one-liner, install, command reference with examples, maybe a demo GIF.

Library / package — developers import it. Needs: one-liner, install, API usage examples with real code, link to full docs if they exist.

Web app / service — users run it locally or deploy it. Needs: one-liner, screenshot or demo, quick start (clone → install → run), environment variables, deploy notes.

Claude Code skill — extends Claude. Needs: one-liner, what it does in plain terms, install (copy to ~/.claude/skills/), trigger examples (what to say to Claude), usage examples.

Script collection / toolkit — a set of related utilities. Needs: one-liner, what problem set it solves, list of scripts with brief descriptions and examples.

Data / research project — analysis notebooks, datasets. Needs: what question it answers, data sources, how to reproduce results.

---

Step 3 — Write the README

Structure (adapt to project type)

# Project Name
One sentence. What it does and why it's useful. Not "A tool that..." — just state the fact.

[badges if appropriate — build status, npm version, license]

## What it does        ← skip if the name + one-liner is already clear
[2-3 sentences or a short bullet list. Focus on outcomes, not features.]

## Install
[shortest possible path to working. Real commands, copy-paste ready.]

## Usage
[1-3 concrete examples. Show real input and real output. Code blocks.]

## Configuration       ← only if non-trivial config exists
[table of env vars / flags / options]

## Contributing        ← for open source projects
[one paragraph or link to CONTRIBUTING.md]

## License
[one line + link]

Leave out any section that doesn't apply. A 40-line README that covers everything is better than a 200-line README with padding.

Voice and tone

Write for a developer who's deciding in 20 seconds whether to use this. They're scanning, not reading. That means:

• Lead with outcomes, not mechanics. "Analyze any MRI scan from a hospital CD" beats "A Python tool that uses pydicom to parse DICOM files."
• Use real examples. Show actual commands, actual output, actual code. Made-up placeholders like <your-value-here> are worse than no example at all.
• Be direct. Cut "This project aims to", "This tool allows you to", "Designed for". Just say what it does.
• Match the project's register. A weekend hack can be casual. A production library should be crisp and precise.

Anti-patterns to cut

• Opening with "This is a..." or "Welcome to..."
• Feature lists that don't explain benefits
• Installation steps that reference tools that aren't installed by default without saying so
• Empty sections ("Coming soon", "TODO")
• Badges for things nobody checks (code coverage of a personal project, etc.)
• License section that just says "MIT" with no context

---

Step 4 — For updates (existing README + changed code)

When the user says the README is out of date or a new feature was added:

1. Read the current README fully
2. Understand what changed (ask the user, or check git log / diff if available)
3. Update only the sections that need it — don't rewrite everything
4. If the install steps changed, verify the new ones actually work
5. If usage examples changed, update them with the real new syntax

Surgical updates beat full rewrites for active projects. Preserve the existing voice.

---

Step 5 — For improvements (existing README that's weak)

When the user wants their README to be better, audit it against this checklist:

• Does the first sentence clearly say what the project does?
• Is there a working install command?
• Is there at least one real usage example with actual code?
• Are there any broken links or outdated commands?
• Are there sections that are empty or say "coming soon"?
• Is it longer than it needs to be? (cut ruthlessly)
• Does it match what the code actually does right now?

Tell the user what you found before rewriting. If only 2 things are wrong, fix those 2 things — don't rewrite the whole file.

---

Output

Write directly to README.md in the project root. If a README already exists, edit it in place rather than replacing wholesale unless the user asked for a full rewrite.

After writing, briefly summarise what you changed and why — especially if you cut sections or made structural choices the user might want to reconsider.