readme-pitch

Rewrite this repository's README into a first-screen pitch. The one-line rule: a reader who knows the domain understands in five seconds what this is, who it is for, what outcome it promises, and what to type next.

You are already invoked. Run the phases in this file against the repo that is the current working tree. The main agent is the only writer. Research briefs do not edit files.

Two kinds of input feed the rewrite. Facts are what the repo can settle (Phase 1 inventory, brief D). Look them up; never ask for them. Decisions are what only the maintainer can settle (who the reader is, the one claim, the register, whether to name rivals). Phase 1b collects them: asked when --ask is given, read from a file with --brief, otherwise recommended from the facts and named out loud in the report. Never decide silently.

This skill is host-neutral. Discover this skill's directory as the folder that contains this SKILL.md (the path the host used to load it). Scripts live at <skill-dir>/scripts/. Map host tool aliases when tallying; do not depend on a plugin-root env var or one vendor's tool names.

Input

Natural language maps onto the flags. "Ask me first", "interview me", "let me choose the pitch" is --ask. "Don't fetch competitors" is --no-research. "Draft only" / "do not overwrite" is --draft-only. --ask with --brief: the round still runs, with the file's answers as the recommendations.

Overwrite policy. After the cold read (Phase 6), show a short diff summary (before/after line counts, sections added or removed, docs that will absorb content, cold-read changes applied), then overwrite README.md on this same turn. Wait for a human only during the --ask round or when they said --draft-only. Showing the summary is the human-visible stop; it is not a blocking checkpoint.

Refuse or flag

Refuse (stop that action, say why, continue the rest):

• Deleting a section whose facts have no docs home yet. Relocate first.
• Editing, weakening, or deleting a test that asserts on README content. Keep the string in the README.
• Restating a number the repo derives (test counts, subcommand counts, cap values). Link to the command that prints it, or omit the number.
• Naming a rival the pitch brief's comparison field does not allow, or one nobody fetched or supplied. Named rivals come from --repos, the pitch brief, or a research report that fetched them, nowhere else.
• Asking the user for a fact the repo can settle, or asking any question in default mode (no --ask), on any host.

Flag (do the rewrite, list each under OUTSIDE THIS CHANGE):

• A hero whose content contradicts the text.
• An unpublished package, before adding a version badge.
• A landing page or site whose copy the new tagline contradicts.
• A missing social preview. A hero the repo still needs designed (see references/hero-guidance.md).

Handoff dir

if [ -d .claude/handoff ]; then HAND=".claude/handoff"
else mkdir -p .agents/handoff; HAND=".agents/handoff"
fi
date +%Y%m%d-%H%M%S

Prefer .claude/handoff when it already exists. Write:

• readme-pitch-inventory-<timestamp>.md
• readme-pitch-brief-<timestamp>.md (Phase 1b; reloaded on re-runs)
• readme-pitch-research-<brief>-<timestamp>.md for every brief that ran (A, B, C, D, E). These are the audit trail for competitor claims.
• readme-pitch-draft-<timestamp>.md (Phase 5)
• readme-pitch-pins-<timestamp>.txt (one pinned string per line)
• readme-pitch-hero-prompt-<timestamp>.md when no usable hero exists

Unavailable I/O: report the item as unavailable, never guess.

Host dispatch (Phase 2 and 6)

Fan-out without asking. Honour a model policy the user stated or that a project instructions file names (AGENTS.md, CLAUDE.md, .cursor/rules). Otherwise use the host default. Do not hard-code a vendor's model names.

Each spawned brief counts toward --max-agents. Default 5 covers A+B+C+D and later E. If the cap is lower, queue. Sequential order when there is no fan-out: D, then C, then A. Skip B unless --repos names competitors. Say which briefs were skipped in the report.

No web tool on the host, or --no-research: skip A, B, and C entirely. Read references/first-screen-rules.md. Degradation is spoken, never silent.

Brief contract (every brief already carries it; substitute the placeholders in memory, then hand the text verbatim): fetch raw READMEs from raw.githubusercontent.com/OWNER/REPO/HEAD/README.md, fall back to main then master; if a fetch fails, say so and move on; count lines with a tool, not by eye; quote taglines verbatim; put per-repo data in tables; end with rules phrased "Do X before Y because Z, as REPO shows". No brief edits files. Honour the word cap.

Scripts

node "<skill-dir>/scripts/check-links.mjs" README.md <other-touched.md...>
bash "<skill-dir>/scripts/check-pins.sh" "$HAND/readme-pitch-pins-<timestamp>.txt" README.md

check-links.mjs is stdlib Node (GitHub slugger semantics, no collapsing). If Node is absent, grep relative links by hand and say so in LINKS:.

Steps

Phase 0: Gate

• Must be a git repository with a README.md. Otherwise stop and say so. Make no edits.
• Read the README once, in full. Record line count and the line number of the first image, first code block, first H2, and the install snippet.
• If the README is already under 150 lines and has an image before the first code block, it meets the bar. Say so, name --force as the way to rewrite it anyway, and stop. Make no edits and emit no report block. Do not ask whether to continue; nobody answers in an unattended run. With --force, continue.

Phase 1: Inventory (deterministic, cheap, before any research)

Gather with file tools and one shell command per call. Best-effort; an unavailable item is reported as unavailable, never guessed.

Archetype signals, in priority order:

Write the inventory to the handoff path above. Phase 5 reads it back.

From README consumers, extract every string a test asserts on. Write those strings, one per line, to the pins file. That file is the contract for Phase 4 and check-pins.sh.

Phase 1b: Pitch brief (decisions)

Read references/pitch-brief.md. Five decisions: reader, archetype, claim, register, comparison. Each gets a recommended answer derived from the inventory (the reference says how).

1. If the handoff dir already holds a readme-pitch-brief-*.md, load the newest as the recommendation source. --brief <path> overrides it. A missing --brief path is reported and ignored.
2. Derive a recommendation for every decision the source leaves blank.
3. Mode:
   • default: take every recommendation. Ask nothing. Not one question, on any host, even one with a question tool.
   • --ask: print the round in the reference's exact shape, end the turn, wait. Parse the reply by number and letter. Unanswered items take the recommendation.
4. Write the brief to $HAND/readme-pitch-brief-<timestamp>.md in the reference's file format. Phases 2, 3, 5, 6, and 8 read it. A re-run in this repo reloads it, so the README's voice is a repo fact, not a per-user setting.

Phase 2: Research fan-out

Read each brief from <skill-dir>/references/briefs/, substitute the placeholders in memory, and pass the result as the agent's prompt (or, with no fan-out, follow it in-process). Never write to the skill directory. If a filled brief must exist on disk, write it to the handoff dir.

Launch A, B, C, D together when the host can and the cap allows. Hold E until Phase 6. Write each returned report to the handoff dir.

Phase 3: Synthesize the target shape

Read references/readme-skeleton.md. Apply the brief's archetype row: it swaps sections 5, 8, and 13 and decides whether the tagline names a host. Comparison skip drops section 10; unnamed keeps it without rivals. Fix the section order and a line budget per section before writing a word. Targets: pitch (sections 1 to 6) complete within 30 rendered lines and about 660 px; whole README 100 to 150 lines; first H2 no later than line 25.

Phase 4: Relocate before cutting

Read references/relocation-checklist.md. Nothing leaves the README until it has a home. From brief D's orphan-fact table:

1. For each group with an existing home, extend that doc at the named heading.
2. For groups with no home, create the smallest number of new files. Two recurring ones: a CLI and configuration reference (every subcommand verified against --help, every environment variable in one table) and a root CONTRIBUTING.md (development commands, conventions, release).
3. Repoint every anchor that pointed into a moved section. GitHub slug rules: lowercase, strip punctuation, each space becomes a hyphen, no collapsing. A heading with a spaced em dash (U+2014) produces a double hyphen: the dash is stripped, both spaces remain.
4. Fix stale counts by removing the number or deriving it, never by updating one literal to another.
5. Keep every string a test asserts on. A pinned string may move within the README but not out of it.

Do relocations with strict single-match replacements so a target that no longer matches fails loudly instead of silently skipping.

Phase 5: Draft

Write the README from the skeleton, the budgets, and the pitch brief. The tagline speaks to the brief's reader, makes its claim, and holds its register. Rules the cold read will otherwise catch:

• No term before its definition. Define at first use or replace with plain words.
• One job per sentence. Split anything over 30 words.
• Bold the first words of a bullet, never a whole sentence.
• The install snippet says where a bare binary comes from before it asks the reader to run one.
• Internal consistency: what the default command does, and what a flag adds, said the same way in the code comment, the flow table, and the bullets.
• No hand-written counts of tests, subcommands, or skills. Derive or omit.

Write the draft to the handoff dir. Do not show a diff summary yet: the cold read changes the draft, and the summary must describe the file that lands.

If no usable hero is in the inventory and --hero was not given, write the design prompt (from references/hero-guidance.md) to handoff and list it under OUTSIDE THIS CHANGE. Do not generate an image. If a usable image exists, place it with an explicit width, before any code block.

Phase 6: Cold read, summary, overwrite

Run brief E against the draft ({{DRAFT_PATH}}, with {{PITCH_BRIEF_PATH}} so it can check the draft against the decisions). Prefer a spawned agent if the --max-agents budget remains; otherwise follow the brief in-process. Apply its top five. Re-run the pin and link checks after.

Then show the diff summary: before/after line counts, sections added or removed, docs that absorbed content, and how many cold-read changes were applied. This is the one human-visible stop. Then overwrite README.md on this same turn unless --draft-only.

Phase 7: Verify

• Links. Every relative link and anchor in every touched file resolves. Run check-links.mjs on those files. Where Node is absent, grep and say so.
• Pins. Every inventory pin is still present. Run check-pins.sh.
• The repo's own test command, from package.json or the project instructions file, run exactly as documented. Paste the tail.
• Plugin or package validation if the repo has one (claude plugin validate, npm pack --dry-run, and the like).

Phase 8: Report

The reply ends with this block, exact labels, one per line. Downstream automation and the evals grep it. Keep honest caveats in the prose above; keep these tokens exact.

README: <before> -> <after> lines
HERO: line <n>, before first code block: yes|no
PITCH COMPLETE BY: line <n>
PINS KEPT: <k>/<k>
LINKS: all resolve | <n> broken
MOVED: <file> (<section>), ...
DECISIONS: <assumed | asked | brief <path>> | reader: <...> | archetype: <...> | claim: <...> | register: <...> | compare: <named|unnamed|skip>
RESEARCH: <ran, pipe-separated> ran | <skipped, pipe-separated> skipped (<reason>)
TESTS: <command> -> <pass>/<fail>
OUTSIDE THIS CHANGE: <one line each>

PITCH COMPLETE BY is the last line of sections 1 to 6 (the pitch), which must equal or precede the first H2.

DECISIONS starts with the source token, then the five decisions in this order. Examples:

• DECISIONS: assumed | reader: a Node developer who already ships a CLI | archetype: cli | claim: turns a long README into a five-second pitch | register: outcome | compare: skip
• DECISIONS: asked | ...
• DECISIONS: brief .claude/handoff/readme-pitch-brief-20260914-101500.md | ...

RESEARCH examples:

• RESEARCH: A|B|C|D|E ran | skipped (none)
• RESEARCH: D|E ran | A|B|C skipped (--no-research)
• RESEARCH: D|E ran | A|B|C skipped (no web tool)
• RESEARCH: A|C|D|E ran | B skipped (no --repos)

When A, B, and C are all skipped, the line must contain the substring A|B|C skipped so evals can grep it.

OUTSIDE THIS CHANGE is one line per flagged item, or none. MOVED is none when nothing relocated.

On either Phase 0 stop (no README, or the README already meets the bar without --force), do not emit this block. Say why the skill stopped, and make no edits.

Related

• Pitch brief, modes, and the DECISIONS line: references/pitch-brief.md
• Distilled first-screen rules: references/first-screen-rules.md
• Skeleton, budgets, and archetype swaps: references/readme-skeleton.md
• Relocate-before-cutting: references/relocation-checklist.md
• Hero choice and design prompt: references/hero-guidance.md
• Briefs: references/briefs/category-survey.md, neighbour-survey.md, pitch-craft.md, internal-audit.md, cold-read.md