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.