readme-writing-stinger

name

readme-writing-stinger

description

Authors, audits, and restructures README files so they convert visitors into users. Apply when the user says "write a README", "audit my README", "make my README better", "README for this project", "README-driven development", or when starting a new project and the README does not exist yet. Also apply when badges are broken or missing, the quickstart is not copy-paste runnable, or the user wants to differentiate between an OSS and an internal tool README. Do NOT apply for full documentation site architecture (library-worker-bee), per-entity code extraction (wiki-worker-bee), or CI badge pipeline wiring (ci-release-worker-bee).

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:

Type	Signal	Template