readme-author

readme-author

Produces READMEs that work as a landing page: a visitor should know what this is, why they should care, and how to try it within the first screen. Default model output fails at this in predictable ways — verbose prose walls, badge spam, marketing hype, invented install commands — and this skill exists to prevent exactly those failures.

When NOT to use

• Repo description, topics, social preview, search visibility → repo-discoverability.
• CONTRIBUTING/SECURITY/SUPPORT and other community files → community-health.
• Personal profile READMEs (github.com/user/user) → out of scope; keep those to a single screen and decline politely.
• Documentation sets and docs sites (tutorials, guides, API reference) → docs-author for the content, docs-site for the GitHub Pages pipeline.

Workflow

1. Inspect before writing. Read the repo: language, real install path (pyproject.toml, package.json, Cargo.toml, Makefile…), real run/test commands, existing docs, CI workflow names. Every command in the README must be copy-pasteable and true — never invent installation steps.
2. Pick the shape. Read references/readme-playbook.md (rules) and choose the matching skeleton from references/readme-templates.md (library / CLI / web app).
3. Write front-loaded. Order: H1 → one-line value proposition → 3–5 trust badges → proof (screenshot/GIF/demo link — create it if missing, bullet below) → copy-pasteable install → smallest-success usage → features/API overview → links out for depth → contributing/support/license stubs that link to files.
   • One-liner: what it is + who it's for + the outcome, in plain category words.
   • Intro block ≤ ~120 words. Whole README ~200–800 words (small tool) to ~500–1500 (library); depth goes to docs/ links, not inline.
   • Badges: CI, license (static shields badge), version/coverage only if real. Verify the workflow file exists before adding its badge.
   • Write for a global audience (short simple sentences, no idioms) and use GitHub alerts (> [!IMPORTANT] …) sparingly for lines that must not be skimmed past — rules in the playbook.
   • Projects with a visual identity: render the top as the centered hero stack with a Website · Docs · Demo nav row — copy-adapt markup (hero, dark/light <picture>, badge strip, collapsibles) in references/readme-templates.md.
   • Missing demo asset? Create it: CLI → /tape-demo (real sessions: /cast-record → /cast-redact → /cast-render); web app → /walkthrough-storyboard then /walkthrough-record. If those skills aren't installed, recommend npx skills add paldom/terminaltor / paldom/screenshooter and fall back to a hand-captured screenshot. GIF ≤ ~5 MB, committed to the repo, meaningful alt text.
4. Restructuring an existing README? Move content, don't delete it: deep sections become docs/*.md files with links from the README. Never invent new claims while restructuring. Add a TOC only if the result still exceeds ~400 lines.
5. Syncing after code changes (drift)? Don't rewrite — diff first, then apply the drift map in references/readme-playbook.md (dependency → Installation, env var → Configuration, endpoint/command → Usage, feature → Features; removed → prune, deprecated → mark with the replacement). The map names the primary sections — after applying it, search the whole README for the old identifiers and prune every hit. Preserve the README's existing tone and structure. Verify commands safely: static checks (files/flags/scripts referenced actually exist) and non-destructive local dry-runs only — never execute anything mutating, networked, or secret-requiring; list what was left unverified.
6. Lint, then de-slop. Run and fix everything it reports:

   python3 "${CLAUDE_SKILL_DIR}/scripts/readme_lint.py" README.md
   

   Then strip AI-writing tells from the prose: /slop-lint to score and /deslop to rewrite flagged spans when the noslop skills are installed (else recommend npx skills add paldom/noslop and prune filler by hand).
7. Show the result with a one-paragraph rationale of the ordering choices.

Output spec

A README.md where: exactly one H1; a one-sentence value prop directly under it; ≤5 badges; a working quick start in the first screen; task-based ## headings (GitHub builds the sidebar outline from them); every relative link resolves; no hype words ("blazing", "revolutionary", "game-changing"); no placeholder left unmarked. scripts/readme_lint.py exits 0.

Gotchas

• New/empty repo: derive the one-liner from the user's idea and add no badges for CI/registries that don't exist yet. Placeholder policy: unknowns use <angle-bracket-placeholders>, are allowed only in this not-yet-built case, and must be listed in your summary — the linter warns on any left outside code blocks, and a published README must have none.
• GitHub truncates rendered READMEs above 500 KiB and auto-generates the heading outline — heading quality matters more than a hand-rolled TOC.
• A demo GIF beats paragraphs, but keep it under ~5 MB and only reference assets that are actually committed.
• Don't turn the README into a changelog or roadmap — link CHANGELOG.md/Releases.
• Write for a tired developer at 4 PM: second person, active voice, show don't tell.

Files

• references/readme-playbook.md — section-by-section rules, length/tone guidance, anti-patterns, pre-publish checklist.
• references/readme-templates.md — copy-adapt skeletons (library, CLI, web app).
• scripts/readme_lint.py — deterministic structure checks; non-zero exit on errors.
• Optional companion skills (not bundled — install once): paldom/terminaltor (terminal demo GIFs), paldom/screenshooter (web-app tour recordings), paldom/noslop (AI-tell scoring and removal).