readme-doctor

Name: readme-doctor
Author: livlign

18stars1forks

How to install readme-doctor?

livlign/claude-skills/readme-doctor

$npx -y skills add livlign/claude-skills --skill readme-doctor

Installs into the current project.

Summary

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 sign

Files · 1

View on GitHub

SKILL.md

1	# readme-doctor
2
3	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.
4
5	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.
6
7	## Phases
8
9	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.
10	2. Audit — walk the rubric, score each criterion, gather evidence (cite line numbers).
11	3. Punch list — prioritize findings P0 (blocking) / P1 (high-leverage) / P2 (nice-to-have), each with a one-line fix.
12	4. Optional output — read-only summary by default; on user request, open a PR with concrete edits.
13
14	---
15
16	## Phase 1 — Discovery
17
18	### 1.1 Operating mode (ask first)
19
20	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.
21
22	### 1.2 Input
23
24	User may provide:
25
26	- GitHub URL → `gh repo view` + clone shallow
27	- Local path → read directly
28	- 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."
29	- Nothing → ask first
30
31	### 1.3 Scan (collect before judging)
32
33	- README full text + rendered length (lines, words, time-to-scan estimate at 250wpm)
34	- Manifest: `package.json`, `Cargo.toml`, `pyproject.toml`, etc. — version, description, keywords
35	- File tree (depth 2): does an `examples/` exist? `docs/`? Image assets?
36	- Recent commits (last 10): is the repo active? When was last release?
37	- GitHub signals: stars, topics, open issues count, latest release date
38
39	### 1.4 Repo classification (drives rubric weighting)
40
41	Categorize the repo from the scan — different categories get different rubric weights:
42
43	- Library / package — installable, imported by other code (npm, PyPI, crates). Weight: install-to-first-success, concrete example, API stability signal.
44	- CLI tool — terminal-run binary or script. Weight: one-line install, single-command demo, output screenshot/GIF.
45	- Framework — opinionated structure others build on (Next, Rails, etc.). Weight: "why this over alternatives," opinionated example, conceptual model.
46	- App / service — runnable thing, not imported (self-hosted, web app). Weight: deploy story, config surface, screenshot.
47	- Standard / spec / docs — knowledge artifact, not code. Weight: scope statement, navigation, change log.
48	- Personal project / experiment — explicitly unstable. Weight: honest scope, "what this isn't," low-friction trial.
49
50	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.
51
52	### 1.5 Audience inference
53
54	Who is this README written for? Infer from jargon density, claimed prerequisites, comparison points named.
55
56	- Working developers in the same domain — assumes vocabulary, optimizes for "do I want this in my project."
57	- Newcomers to the domain — explains terms, shows simple example before deep one.
58	- Maintainers / power users — assumes deep familiarity, optimizes for reference.
59	- Mixed — most common; means the README needs explicit on-ramps for each.
60
61	A README that's pitched at the wrong audience for its category is the single most common shape problem. Catch it here.
62
63	---
64
65	## Phase 2 — Audit (the rubric)
66
67	Each criterion: score 1–5 with one-line evidence and (for any score ≤3) one-line fix. Default 3, evidence required to move.
68
69	### 2.1 The "what is this" sentence
70
71	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?
72
73	- 5: One sentence, no jargon, names the category and the differentiator
74	- 3: Says what it is but buries the "why" or

People who liked this also viewed

6 picks

Type

readme-doctor

18stars1forks

View on GitHub

How to install readme-doctor?

livlign/claude-skills/readme-doctor

$npx -y skills add livlign/claude-skills --skill readme-doctor

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# readme-doctor
2
3	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.
4
5	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.
6
7	## Phases
8
9	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.
10	2. Audit — walk the rubric, score each criterion, gather evidence (cite line numbers).
11	3. Punch list — prioritize findings P0 (blocking) / P1 (high-leverage) / P2 (nice-to-have), each with a one-line fix.
12	4. Optional output — read-only summary by default; on user request, open a PR with concrete edits.
13
14	---
15
16	## Phase 1 — Discovery
17
18	### 1.1 Operating mode (ask first)
19
20	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.
21
22	### 1.2 Input
23
24	User may provide:
25
26	- GitHub URL → `gh repo view` + clone shallow
27	- Local path → read directly
28	- 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."
29	- Nothing → ask first
30
31	### 1.3 Scan (collect before judging)
32
33	- README full text + rendered length (lines, words, time-to-scan estimate at 250wpm)
34	- Manifest: `package.json`, `Cargo.toml`, `pyproject.toml`, etc. — version, description, keywords
35	- File tree (depth 2): does an `examples/` exist? `docs/`? Image assets?
36	- Recent commits (last 10): is the repo active? When was last release?
37	- GitHub signals: stars, topics, open issues count, latest release date
38
39	### 1.4 Repo classification (drives rubric weighting)
40
41	Categorize the repo from the scan — different categories get different rubric weights:
42
43	- Library / package — installable, imported by other code (npm, PyPI, crates). Weight: install-to-first-success, concrete example, API stability signal.
44	- CLI tool — terminal-run binary or script. Weight: one-line install, single-command demo, output screenshot/GIF.
45	- Framework — opinionated structure others build on (Next, Rails, etc.). Weight: "why this over alternatives," opinionated example, conceptual model.
46	- App / service — runnable thing, not imported (self-hosted, web app). Weight: deploy story, config surface, screenshot.
47	- Standard / spec / docs — knowledge artifact, not code. Weight: scope statement, navigation, change log.
48	- Personal project / experiment — explicitly unstable. Weight: honest scope, "what this isn't," low-friction trial.
49
50	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.
51
52	### 1.5 Audience inference
53
54	Who is this README written for? Infer from jargon density, claimed prerequisites, comparison points named.
55
56	- Working developers in the same domain — assumes vocabulary, optimizes for "do I want this in my project."
57	- Newcomers to the domain — explains terms, shows simple example before deep one.
58	- Maintainers / power users — assumes deep familiarity, optimizes for reference.
59	- Mixed — most common; means the README needs explicit on-ramps for each.
60
61	A README that's pitched at the wrong audience for its category is the single most common shape problem. Catch it here.
62
63	---
64
65	## Phase 2 — Audit (the rubric)
66
67	Each criterion: score 1–5 with one-line evidence and (for any score ≤3) one-line fix. Default 3, evidence required to move.
68
69	### 2.1 The "what is this" sentence
70
71	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?
72
73	- 5: One sentence, no jargon, names the category and the differentiator
74	- 3: Says what it is but buries the "why" or

People who liked this also viewed

6 picks

Type