---
name: readme-architect
description: "Generate a README that earns GitHub stars — hero, features, install, quickstart, screenshots, badges. Reads your repo and writes a README.md with the structure that wins on GitHub: hero pitch + badges, one-line feature list, fast install + quickstart, code examples, screenshots/GIFs section, contributing, license. No empty templates."
license: MIT
---

# 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

```bash
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.