CommunityProductivity & Collaborationgithub.com

readme-writer

Writes or rewrites a project README that converts visitors into users and contributors - one-line pitch, badges, a 60-second quick start, real examples, features, FAQ, contributing and license - and lints it for missing sections, broken relative links, table-of-contents anchors that match no heading, missing alt text and a late first code block. Use when the user asks to write, improve, review or restructure a README, says nobody understands or stars the project, or is preparing an open-source launch.

What is readme-writer?

readme-writer is a Claude Code agent skill that writes or rewrites a project README that converts visitors into users and contributors - one-line pitch, badges, a 60-second quick start, real examples, features, FAQ, contributing and license - and lints it for missing sections, broken relative links, table-of-contents anchors that match no heading, missing alt text and a late first code block. Use when the user asks to write, improve, review or restructure a README, says nobody understands or stars the project, or is preparing an open-source launch.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/saizul/oss-maintainer-skills/tree/HEAD/skills/readme-writer

Installed? Explore more Productivity & Collaboration skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

README writer

A README has one job: get a visitor from "what is this?" to a working first command in under a minute, then show them how to go further and how to help.

When to use

  • Writing a README for a new project, or rewriting a thin or rambling one
  • Reviewing a README before a launch or a 1.0 release
  • The user says the project gets visits but no stars, installs or contributors

When not to use

  • API reference documentation (generate it from code; link it from the README)
  • Long tutorials or architecture docs: put them in docs/ and link them

Workflow

  1. Gather facts before writing. Read the manifest (pyproject.toml, package.json, composer.json, Cargo.toml...), the CLI --help or main entry point, existing docs, and the license. Find the real install command and a real example. Never invent flags, outputs, benchmarks or features.

  2. Ask the user only what the code cannot tell you: who the project is for, the one problem it solves, and why it is better than the obvious alternative. If they are not available, write a neutral pitch from the code and mark it for review.

  3. Lint the current README (if there is one). scripts/ is relative to this skill:

    python3 scripts/readme_lint.py README.md
    python3 scripts/readme_lint.py README.md --json --strict
    
  4. Write using the structure in structure.md, starting from the template. Order matters: title + badges, pitch, (demo image), quick start, features, usage/examples, configuration, FAQ, roadmap, contributing, license.

  5. Apply the writing rules:

    • Pitch: one sentence, under 200 characters, no hype words. Pattern: "<name> is a <category> that <does X> for <audience>, <key differentiator>."
    • First code block above line 60. Every command must be copy-pasteable and real.
    • Show output after commands where it helps (# => ... or a separate block).
    • Use tables for options and comparisons, lists for features (benefit first).
    • Link, don't paste: long docs, changelogs and API references go elsewhere.
    • Every image gets alt text; prefer an SVG or a short GIF of the main flow.
  6. Badges. Use only badges that are true and maintained, in this order: CI status, latest version (PyPI/npm/Packagist/release), downloads (optional), license. Examples in structure.md.

  7. Re-lint until there are no errors. Resolve warnings or tell the user why not.

  8. Check the links the linter cannot: absolute URLs and anchors. Click-test or explain which were not verified.

Output

  • The new or updated README.md (show a diff summary for rewrites).
  • The final lint result.
  • A short list of facts you could not verify and placeholders the user must fill (demo GIF, screenshots, benchmark numbers).

Lint rules

RuleLevelMeaning
titleerror/warningexactly one H1
pitcherror/warninga short first paragraph under the title
badgeswarningno badge found
installerror/warninginstall (or quick start) section, with a code block
quickstarterror/warningusage, quick start or example section, with code
codeerrorno code block at all
scrollwarningfirst code block after --max-scroll lines (default 60)
contributing, licensewarningmissing section
faq, tocinfosuggested
alt-textwarningimage without alt text
broken-linkerrorrelative link to a missing file, or an empty link
broken-anchorerror#anchor link (table of contents) that matches no heading or HTML id/name, using GitHub's slug rules
placeholderwarningTODO, TBD or lorem ipsum left in

Exit 1 on errors (and on warnings with --strict).

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Related Skills