gabrielmoreira 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.
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).