---

name: readme-writer description: "Write a clear, well-structured README for a software project or open-source repo. Use when asked to write or improve a README, document a project, or make a repo approachable. Produces a complete README — one-line pitch, badges, quickstart, usage, install, contributing, license — that gets someone from landing to running fast."

README Writer Skill

The README is a project's front door — most people decide in seconds whether to use or bounce. This skill writes a clear, scannable README that answers what is this, why should I care, how do I run it immediately, then layers in the detail. Structured so a newcomer gets to a working result fast.

Not quite this? Use readme-benefit-writer when you already have a README and want each feature rewritten as a user benefit.

Required Inputs

Ask for these only if they aren't already provided:

• Project name & one-line purpose — what it is and what problem it solves.
• Who it's for — the target user/developer.
• Install & basic usage — how to install and the simplest working example.
• Key features / differentiators — the few things that matter most.
• Project facts (optional) — language, license, links (docs, demo), contribution policy, status (alpha/stable).

Output Format

A complete README.md:

[Project name]

One-line pitch — what it does and for whom.

(Badges line — build, version, license — as placeholders to fill.)

Why [project]? — 2–3 sentences or bullets: the problem and what makes this worth using (honest, specific).

Features — the handful that matter, as a tight bullet list.

Quickstart

# install
# minimal working example

…with the expected result shown.

Usage — the common cases, with short code examples. Link out to full docs rather than inlining everything.

Installation — fuller install/requirements if the quickstart was minimal.

Contributing — how to contribute / link to CONTRIBUTING; be welcoming.

License — the license line.

(Adapt sections to the project; omit what doesn't apply. Keep it scannable with clear headings.)

Quality Checks

• Opens with a one-line pitch that says what it is and for whom
• A newcomer can copy-paste the quickstart to a working result
• "Why this" is specific and honest, not generic praise
• Scannable structure (headings, short sections); deep detail is linked, not dumped
• Install, usage, contributing, and license are all covered (or consciously omitted)

Anti-Patterns

• Do not bury what-it-does under a wall of badges or backstory — pitch first
• Do not write a quickstart with missing steps — it must actually run
• Do not inline the entire documentation — summarize and link
• Do not over-promise; reflect the real project status (alpha/beta/stable)
• Do not skip the license — it determines whether anyone can legally use it

Based On

Open-source README best practices (one-line pitch, time-to-first-success quickstart, scannable structure, standard sections).

Example Trigger Phrases

• "Improve a README."
• "Document a project."
• "Make a repo approachable."