make-readme

Files (9)

• README_TEMPLATE.md
• SKILL.md
• badges.md · references/
• evidence.md · references/
• project-types.md · references/
• section-playbook.md · references/
• corpus_analyzer.py · scripts/
• inspect_repo.py · scripts/
• score_readme.py · scripts/

SKILL.md (first lines)

# make-readme

Produce a README that a stranger can evaluate in ten seconds and use in sixty.

The structure here is not taste. It comes from measuring the 40 most-starred OSS developer-tool
repositories on GitHub (September 2026), 114 curated "great README" write-ups, and six
mainstream guides. `references/evidence.md` carries the numbers and the method. When a decision
is contested, the corpus wins.

## Non-negotiable rules

1. **Never invent facts.** No benchmark numbers, no feature you have not seen in the code,
   no license you have not read in the LICENSE file, no Discord link you cannot verify, no
   install method the repo does not document. If a fact is missing, either omit the element or
   ask. An impressive lie in a README is a bug report.
2. **Never link a file that does not exist.** CONTRIBUTING.md, SECURITY.md, LICENSE, docs/,
   images: check each one on disk before linking it. Offer to create the missing file instead.
3. **Read the manifest for every version claim.** Runtime floors, package names, extras, and
   entry points come from `pyproject.toml`, `package.json`, `Cargo.toml`, or `go.mod`, never from
   memory or from the previous README. Version drift between README and manifest is the most
   common factual defect found in real repos.
4. **Verify commands.** Every install and quick-start command must be traceable to a manifest,
   a published package, or a script in the repo. Run them when the environment allows it. Mark
   anything you could not verify and tell the user in your summary.
5. **Cut before you add.** The median top-tier README is ~128 lines and ~10 sections. A section
   that exists because a template had it is worse than no section.
6. **Preserve what already works.** When improving an existing README, keep its working badges,
   real community links, hard-won troubleshooting notes, its voice, and the product's own
   nouns. You are editing, not replacing a person's work.

## Workflow

### Step 1: Establish mode and target

- `create`: no README, or the user wants a fresh one.
- `improve`: a README exists. Default to this whenever one is present.
- `review`: the user wants a critique or score only. Do Steps 2 and 6, skip the writing.

If the target is a remote repo, clone it shallowly first
(`git clone --depth 1 <url>`); if you cannot clone, fetch the raw README and work from the
user's answers alone, and say plainly that repo facts were unverified.

### Step 2: Gather facts from the repo, not from memory

```bash
python3 scripts/inspect_repo.py /path/to/repo
```

This prints identity, binary names, justfile recipes, manifests, ecosystems, likely install
commands, license detection, CI workflows, docs dirs, media assets, community links, health
files, and a GAPS list. H1 is NAME (already BINARIES[0] when present). REPO is the git folder.
Extra console scripts stay on BINARIES. Then read enough of the actual code to describe it
honestly: the entry point, the main module or CLI definition, one real usage path. A README
written from the manifest alone reads like it was written from the manifest alone.

If a README already exists:

```bash
python3 scripts/score_readme.py /path/to/repo/README.md --repo /path/to/repo
```

Corpus calibration: the 40 top-starred repos score a median of 81 on this rubric
(p25 75, p75 89, range 59 to 98). Target 90+, and never ship with a CRITICAL failure.

### Step 3: Classify the project and pick the preset

Read `references/project-types.md` and choose one: CLI tool, library/SDK, web app or
self-hosted service, framework, AI agent/model tool, plugin/extension, monorepo,
research/dataset, internal repo, or template repo. The preset decides which optional
sections survive and what the hero visual should be.

### Step 4: Ask only what you cannot determine

Ask at most 3 to 5 questions, in one batch, only for facts the repo cannot answer. The usual
unknowns: who the audience is, whether a hosted version exists, which support channel is
actually monitored, whether a demo asset can be produced, and any license nuance. Include
your best guess with each question so the user can confirm rather than compose.

If the user is unavailable (unattended run), pick the most conservative reading, omit any
element that would require an unverified claim, and list every assumption at the top of
your final summary. For the hero command, use the launch that the existing README, shims, or
`--help` already treat as primary; do not infer a profile from the language or stack.

### Step 5: Write

Work from `README_TEMPLATE.md`. Its inline instruction blocks carry the per-section rules;
`references/section-playbook.md` carries the reasoning and the failure modes, and
`references/badges.md` has copy-paste badge URLs. Keep only the CLI catalog or the library
example; delete the unused skeleton so placeholders cannot leak.

Canonical order (median positions from the corpus):

1. Header block: logo (optional), binary or product name (not the git slug), tagline, 3 to 6 badges
2. Hero visual: GIF for a CLI, screenshot for an app, first code block for a library
3. Features: 3 to 6 bullets, bold benefit first, differentiators only (7 to 8 only if each is a distinct shipped capability)
4. Installation: one primary command, prerequisites on one line; extras only if they are real, documented, and internally consistent
5. Quick start: CLI = one commented command catalog, at most 8 invocations plus `--help` (overflow in `<details>` or docs/); library = smallest example plus printed result. Delete the unused template skeleton.
6. At most one domain section: integrations table, deployment, comparison, or architecture
7. Documentation: docs home plus up to 3 deep links
8. Community and support: routed by intent, 2 to 4 lines
9. Contributing: one sentence plus a link to CONTRIBUTING.md
10. License: one line, named explicitly, always last

Writing rules that the corpus and the guides agree on:

- Second person, present tense, active voice. "Install it with", not "It can be installed by".
- Lead every section with the thing itself, not with a preamble sentence.
- Language-tag every fence. No `$` prompts inside copyable blocks.
- Relative links for in-repo files; absolute only for external sites.
- Alt text on every image.
- Exactly one H1. No skipped heading levels.
- No emoji in heading text (10% of the corpus; it ages badly and breaks anchors).
- No table of contents under ~150 lines; GitHub generates an outline automatically.
- Tables only for genuinely tabular reference data, capped at ~12 rows.
- Do not describe unreleased work in the present tense.
- H1 is the binary or product name people type, not the git folder.
- Copy the project's own nouns from the existing README and `--help`. Do not rename the product to match implementation jargon.
- The first CLI command is the launch that the existing README, shims, or `--help` already treat as primary; do not infer it from the language or stack.
- For a library, Quick start stays a tiny example plus what it prints. Do not flatten a library README into a command catalog. Delete the bash catalog skeleton.

From sazlin/loadout, MIT.

More from sazlin/loadout