Readme Writing Stinger

readme-writing-stinger

The README is a landing page, not a manual. A visitor makes a go/no-go decision in 30 seconds. Every structural choice this skill encodes (section order, length limits, badge count, quickstart discipline) derives from that constraint.

This stinger encodes five bodies of knowledge:

1. Structural discipline: the canonical 2026 section order and length thresholds.
2. Badge hygiene: which badges earn their spot, which are vanity noise.
3. OSS vs internal: two audiences, two registers, two templates.
4. README-driven development (RDD): write the README before the code.
5. Done criteria: a 12-point checklist to validate before any output is committed.

First action

Read guides/00-principles.md before touching any file. It anchors the "landing page, not manual" mindset and the 30-second visitor window that every guide section cites.

Procedure

Step 1: Classify

Identify the project type from the user's input or by reading the repo:

When in doubt, ask. Classifying wrong means the wrong template and wrong tone, the fastest way to produce a README the user won't use.

Step 2: Audit the existing README

If a README.md already exists, read it fully before proposing any changes. Run the checklist in guides/05-done-checklist.md mentally and emit a brief audit table:

| Section          | Status  | Notes                          |
|------------------|---------|--------------------------------|
| Title/tagline    | ✅ pass |                                |
| Badges           | ⚠️ warn | 8 badges, 3 are vanity noise   |
| One-liner        | ❌ fail | Missing                        |
| Quickstart       | ⚠️ warn | Assumes env vars not explained |

Surface what is already good before proposing rewrites. The user may have intentional choices.

Step 3: Apply the section structure

Follow the canonical order from guides/01-structure-checklist.md:

1. Title + one-liner tagline
2. Badges (3-5 max, status-only)
3. Hero image or demo GIF (OSS only; skip for internal)
4. One-liner pitch (one sentence, no jargon)
5. Quickstart (5 commands max, copy-paste runnable)
6. Features (bulleted, 5-8 items)
7. Install (complete, works on fresh machine)
8. Usage / examples (at least one code block per main use case)
9. Configuration (if applicable)
10. Contributing
11. License

Table of contents only if 5+ sections. See guides/01-structure-checklist.md for pass/fail criteria per section.

Step 4: Apply badge discipline

Follow guides/02-badges.md. Max 3-5 badges in the header. Approved types: CI/CD status, test coverage, version/release, downloads, license. Strip vanity badges (heart badges, "PRs welcome" without evidence, broken/stale).

Step 5: Apply OSS vs internal lens

Follow guides/03-oss-vs-internal.md. Determine the register (skeptical time-poor developer vs trusting teammate) and apply the matching tone throughout. Do not mix registers.

Step 6: Apply RDD if starting from scratch

If the user is starting a new project without existing code, follow guides/04-rdd.md. Write the README as if the product already exists, using present tense. The README becomes the API spec before implementation begins.

Step 7: Final validation

Run guides/05-done-checklist.md end to end. Every item must pass before emitting the final README. Emit the completed checklist inline for the user to review.

What "done" looks like

• The README is under 1,500 words (or extraction is flagged at 2,000 words).
• The quickstart block is copy-paste runnable: tested mentally against a fresh machine with no prior context.
• Badge count is 3-5, all dynamic, all CI/status-class.
• Every section listed in Step 3 is present (or explicitly omitted with a reason).
• The checklist in guides/05-done-checklist.md passes all 12 points.

Handoffs

Folder layout

readme-writing-stinger/
├── SKILL.md                         (this file, master index)
├── README.md                        (human overview)
├── guides/
│   ├── 00-principles.md             (the "landing page not manual" manifesto)
│   ├── 01-structure-checklist.md    (canonical section order + pass/fail criteria)
│   ├── 02-badges.md                 (badge discipline, approved types, Shields.io patterns)
│   ├── 03-oss-vs-internal.md        (two registers, two templates)
│   ├── 04-rdd.md                    (README-driven development)
│   └── 05-done-checklist.md         (12-point validation)
├── examples/
│   ├── before-after-oss.md          (OSS library README before and after)
│   └── before-after-internal.md     (internal tool README before and after)
├── templates/
│   ├── oss-library-readme.md        (fill-in-the-blanks OSS template)
│   └── internal-tool-readme.md      (fill-in-the-blanks internal tool template)
├── reports/
│   └── README.md                    (past audit summaries accumulate here)
└── research/                        (DO NOT MODIFY, authored by scripture-historian)
    ├── research-plan.md
    ├── research-summary.md
    ├── index.md
    └── external/
        ├── 2026-05-20-readme-structure-best-practices.md
        ├── 2026-05-20-readme-driven-development.md
        ├── 2026-05-20-shields-io-badges.md
        └── 2026-05-20-awesome-readme-gallery.md

Part of The Hive, curated by Mario Aldayuz a.k.a @thenotoriousllama.