README Architect

README Architect reads your repository and writes a README.md that follows the structure proven to convert GitHub visitors into stars and users: a sharp hero pitch, status badges, a scannable feature list, copy-paste install and quickstart, real code examples drawn from your own source, and a screenshots/GIFs section. It is built for maintainers shipping an open-source library, CLI, or app who have working code but a thin or missing README.

When to use it

• You just pushed a project public and the README is one line (or the default template).
• Your repo has grown and the README no longer matches the actual API or install steps.
• You're preparing a launch (Show HN, Product Hunt, Reddit) and need the front page to land in the first five seconds.
• You maintain several repos and want a consistent, professional house style across all of them.

How it works

The skill inspects the repo before writing a word. It reads package.json, pyproject.toml, Cargo.toml, or go.mod to detect the language, package name, and install command; scans src/, examples/, and entry points to pull real function names and CLI flags into the code samples; and checks for an existing LICENSE and CI config to generate accurate badges. It assembles the standard high-converting layout — hero + badges, features, install, quickstart, usage, screenshots placeholder, contributing, license — and writes README.md. Nothing is left as <TODO> boilerplate; every section is filled from what's actually in your repo.

Usage

curl -fsSL --create-dirs -o ~/.claude/skills/readme-architect/SKILL.md https://claudeskil.com/skills/readme-architect/SKILL.md

# in your project root
claude "use readme-architect to write my README"

It will report what it detected (e.g. "Python package httpcache, installs via pip install httpcache, MIT license, GitHub Actions CI") and produce a README.md you can edit. To target a subdirectory or monorepo package, just point it there: "write a README for packages/cli".

Tips & gotchas

• Screenshots stay manual. The skill writes the section with correctly-pathed ![](docs/demo.gif) markers, but it cannot capture images — drop your real assets in and the links just work.
• Badges reflect reality, not aspiration. A coverage badge only appears if it finds a coverage config; don't expect a green shield it can't back up.
• Run it from the repo root so it can read your manifest files; running from a random subfolder gives it less to work with.
• It overwrites README.md. Commit or stash your current one first if you want a clean diff to review.

FAQ

Does it invent features I don't have? No. Feature bullets and code samples are derived from your actual source and manifest. If a capability isn't in the code, it won't claim it.

Can it match my existing tone? Pass it an example or your old README and ask it to keep the voice; it adapts the copy while keeping the proven section order.

What if my project isn't in JS/Python/Rust/Go? It still produces the full structure and writes install/usage from whatever build or run files it finds — you may just tweak the install line.