# Readme Doctor > Audit a GitHub repo's README against best-practice patterns and produce a prioritized punch list of fixes. Runs a structured review covering hero presence, install-to-first-success length, "what is this in one sentence" clarity, audience-jargon match, scannability, and drift signals (stale versions, dead links, badge sprawl). Read-only diagnostic; opens a PR only when the user explicitly asks. - **Type:** Skill - **Install:** `agentstack add skill-livlign-claude-skills-readme-doctor` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [livlign](https://agentstack.voostack.com/s/livlign) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [livlign](https://github.com/livlign) - **Source:** https://github.com/livlign/claude-skills/tree/main/plugins/repo-doctor/skills/readme-doctor ## Install ```sh agentstack add skill-livlign-claude-skills-readme-doctor ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # readme-doctor Most README problems aren't typos or missing sections — they're shape problems: the hero never lands, install-to-first-success buries the lede, the "what is this" sentence assumes prior context, the badge row is louder than the content. This skill audits a README against patterns that consistently correlate with maintainer outcomes (stars, contributor onboarding, issue quality) and produces a punch list a maintainer can act on in an afternoon. The skill's quality comes from the **rubric being grounded in the repo's actual audience and category**, not from a generic checklist. A README for a 50K-star framework needs different things than a personal-project utility. ## Phases 1. **Discovery** — pick operating mode (Auto / Semi-auto / Manual, §1.1), input the README, infer the repo's category and audience from the scan, agree on what "good" looks like for this specific repo. 2. **Audit** — walk the rubric, score each criterion, gather evidence (cite line numbers). 3. **Punch list** — prioritize findings P0 (blocking) / P1 (high-leverage) / P2 (nice-to-have), each with a one-line fix. 4. **Optional output** — read-only summary by default; on user request, open a PR with concrete edits. --- ## Phase 1 — Discovery ### 1.1 Operating mode (ask first) Same three modes as `repo-visuals` — Auto, Semi-auto (recommended), Manual. Use `AskUserQuestion`. Mode affects how many decisions are silent vs surfaced; it does not skip rubric checks. ### 1.2 Input User may provide: - **GitHub URL** → `gh repo view` + clone shallow - **Local path** → read directly - **Pasted README text** → analyze in place, but the rubric loses any check that needs file-tree context (manifest signals, screenshot presence, `examples/` dir, etc.). Flag these as "skipped — paste-only mode." - **Nothing** → ask first ### 1.3 Scan (collect before judging) - README full text + rendered length (lines, words, time-to-scan estimate at 250wpm) - Manifest: `package.json`, `Cargo.toml`, `pyproject.toml`, etc. — version, description, keywords - File tree (depth 2): does an `examples/` exist? `docs/`? Image assets? - Recent commits (last 10): is the repo active? When was last release? - GitHub signals: stars, topics, open issues count, latest release date ### 1.4 Repo classification (drives rubric weighting) Categorize the repo from the scan — different categories get different rubric weights: - **Library / package** — installable, imported by other code (npm, PyPI, crates). Weight: install-to-first-success, concrete example, API stability signal. - **CLI tool** — terminal-run binary or script. Weight: one-line install, single-command demo, output screenshot/GIF. - **Framework** — opinionated structure others build on (Next, Rails, etc.). Weight: "why this over alternatives," opinionated example, conceptual model. - **App / service** — runnable thing, not imported (self-hosted, web app). Weight: deploy story, config surface, screenshot. - **Standard / spec / docs** — knowledge artifact, not code. Weight: scope statement, navigation, change log. - **Personal project / experiment** — explicitly unstable. Weight: honest scope, "what this isn't," low-friction trial. State the inferred category back to the user with one-line evidence ("inferred CLI tool — `bin/` entry in package.json, README opens with a `$ npx` line"). In Auto mode proceed silently; Semi-auto/Manual let the user override. ### 1.5 Audience inference Who is this README written for? Infer from jargon density, claimed prerequisites, comparison points named. - **Working developers in the same domain** — assumes vocabulary, optimizes for "do I want this in my project." - **Newcomers to the domain** — explains terms, shows simple example before deep one. - **Maintainers / power users** — assumes deep familiarity, optimizes for reference. - **Mixed** — most common; means the README needs explicit on-ramps for each. A README that's pitched at the wrong audience for its category is the single most common shape problem. Catch it here. --- ## Phase 2 — Audit (the rubric) Each criterion: **score 1–5** with one-line evidence and (for any score ≤3) one-line fix. Default 3, evidence required to move. ### 2.1 The "what is this" sentence The first sentence after the title should answer "what is this thing" without prior context. Test: imagine a stranger landing here from a Hacker News link. Do they know what it is in 10 seconds? - 5: One sentence, no jargon, names the category and the differentiator - 3: Says what it is but buries the "why" or assumes prior context - 1: Slogan, brand-voice, or lists features before saying what it is ### 2.2 Hero presence above the fold Above-the-fold = first ~25 lines, before any heading deeper than H2. Does the README open with an image, GIF, or visible-output block that makes the project's value legible without reading? - 5: Visual hero matches the project's identity (CLI: terminal screencast; UI: screenshot; framework: code sample) - 3: Has a visual but it's generic (logo only, badge row pretending to be a hero) - 1: No visual; opens with prose or badge sprawl ### 2.3 Install-to-first-success length Count the lines (or clicks) from "I want to try this" to "I see the thing working." Less is more. Measure as: line of first install command → line of first runnable example → line of first observable output. - 5: ≤ 3 lines, all copy-pasteable - 3: 4–8 lines, requires switching contexts (file edits) - 1: > 8 lines, or requires a full project setup before any output ### 2.4 Concrete example before API docs Does a runnable, real-world-shaped example appear before the reference docs / option list / config schema? - 5: Example is realistic (named entities from the domain, not `foo/bar/baz`), runs end-to-end as shown - 3: Has an example but it's contrived or after the API table - 1: No example, or example is just `import foo from 'foo'` ### 2.5 Audience-jargon match Does the jargon density match the audience inferred in §1.5? - 5: Jargon load matches audience; unfamiliar terms are linked or briefly defined on first use - 3: Mostly matches but a few terms are introduced cold - 1: Pitches a tool to newcomers using domain-expert vocabulary, or vice versa ### 2.6 Scannability Headings, paragraphs, lists, tables — can a skim-reader find what they need in 30 seconds? - 5: Clear H2s, short paragraphs, tables for comparable choices, no walls of prose - 3: Has structure but inconsistent heading depth or one big prose blob hides key info - 1: Wall of text, deep heading nesting, or so many H2s the TOC is unusable ### 2.7 Drift signals Things that should not be in a README a year later: - **Stale versions** — hardcoded version numbers in prose (not badges) that don't match latest release - **Dead links** — broken anchors, removed-org URLs, archived dependencies - **Badge sprawl** — more than ~5 badges, or badges from defunct services - **TODO / WIP markers** in shipped sections - **Outdated screenshots** — UI shown doesn't match current build Score: - 5: None - 3: 1–2 signals - 1: 3+ signals ### 2.8 "What this isn't" honesty For non-1.0 / personal / experimental projects: does the README set scope honestly? "This is a weekend project. It works for X. It will not handle Y." - 5: Explicit scope statement; unsupported cases named - 3: Stable / production framing implied but not earned - 1: Personal experiment pitched as production-ready (Skip this check for repos clearly past 1.0 with active maintenance.) ### 2.9 Contribution surface For repos that want contributors: is there a low-friction on-ramp? `CONTRIBUTING.md`, "good first issue" labels, dev-setup section? - 5: Clear contribution path with at least one named entry point - 3: `CONTRIBUTING.md` exists but is generic boilerplate - 1: No contribution surface, but the repo otherwise reads as wanting contributors (Skip for repos that explicitly don't accept contributions.) --- ## Phase 3 — Punch list Convert scored criteria into a prioritized list: - **P0 (blocking)** — score ≤ 2 on §2.1, §2.2, §2.3, or §2.4. These are the criteria that determine whether a stranger-from-HN tries the repo at all. - **P1 (high-leverage)** — score ≤ 2 on any other criterion, OR score = 3 on a P0 criterion. - **P2 (nice-to-have)** — everything else with room to improve. For each item: **what's wrong** (one sentence, citing line numbers), **why it matters** (one sentence tied to the inferred audience), **suggested fix** (one sentence, concrete enough to act on). Display the punch list grouped by priority. In Auto mode, also output an overall README health score (simple average of the rubric × 20 = /100). --- ## Phase 4 — Optional output By default this skill is **read-only**. The punch list lives in the chat. If the user asks ("write the fixes," "open a PR," "apply P0/P1"): 1. Confirm scope (which priority tier, which specific items) 2. Edit `README.md` locally — minimal diffs, one item per commit ideally 3. Same upstream-PR machinery as `repo-visuals` Phase 5: detect ownership, fork if needed, open PR with the punch list as the PR description, alt-text where relevant Never auto-apply edits without explicit user confirmation. This skill's value is the diagnosis; the surgery is the user's call. --- ## What this skill does NOT do - Does not rewrite the README in the maintainer's voice — that's a different skill (and risky) - Does not auto-open PRs — only on explicit ask, and only after showing the diff - Does not score visual quality of screenshots/GIFs (that's `repo-visuals`'s job) - Does not lint markdown syntax (use `markdownlint` for that) - Does not generate badges or shields.io URLs ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [livlign](https://github.com/livlign) - **Source:** [livlign/claude-skills](https://github.com/livlign/claude-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-livlign-claude-skills-readme-doctor - Seller: https://agentstack.voostack.com/s/livlign - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.