review-docs
Skill15 starsChanged 5 months agoMITView on GitHub
Review the README or a documentation page from several real reader points of view at once. Fans out one parallel reviewer per audience — Claude Code newcomer, power user, plugin/skill author, skeptical senior engineer, non-running decision-maker — each scoring it x/5 and naming concrete, line-level fixes. Use when asked to review, critique, grade, or "get to N/5" the README or any front-door doc, or to check how a doc reads for real users. Not for code review (use /code-review for that).
23 other projects use a version of this.
Adopted by
Most recently taken up by
- heypinchy/pinchytheir own version, first seen Nov 12, 2026
- opensanctions/opensanctionstheir own version, first seen Nov 1, 2026
- desbma/agent-skillstheir own version, first seen Oct 27, 2026
- FranciscoMoretti/chat-jstheir own version, first seen Oct 19, 2026
- Kaggle/kaggle-environmentstheir own version, first seen Oct 9, 2026
- app-dev-panel/app-dev-paneltheir own version, first seen Oct 8, 2026
Used with
Projects with it also use create-vercel-ai-issue, dev-auth-bypass and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
FranciscoMorettiSkillcreate-vercel-ai-issue
Create a well-formed GitHub issue in vercel/ai using the gh CLI. Use when reporting an AI SDK bug or preparing an issue body that contains logs, code blocks, versions, reproduction steps, and shell-sensitive text.
Also in 3 projects that use this
FranciscoMorettiSkilldev-auth-bypass
Authenticate a browser against a local ChatJS app without OAuth. Use for development login, local auth bypass, authenticated browser or Playwright testing, and the /api/dev-login route.
Also in 3 projects that use this
- +10 more from FranciscoMoretti
Other versions23 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 23
- tldraw/tldraw★ 51ksame name
- videojs/video.js★ 40ksame name
- reactjs/react.dev★ 12ksame name
- hashicorp/terraform-provider-aws★ 11ksame name
- JamieMason/syncpack★ 2.1ksame name
- OpenAEV-Platform/openaev★ 1.8ksame name
- FranciscoMoretti/chat-js★ 1.2ksame name
- FranciscoMoretti/chatjs★ 1.2ksame name
- FranciscoMoretti/sparka★ 1.2ksame name
- opensanctions/opensanctions★ 870same name
13 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository24 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- examples/CLAUDE.mdCLAUDE.md
- src/CLAUDE.mdCLAUDE.md
- add-a-linterSkill
- audience-checkSkill
- audit-feedback-loopSkill
- code-qualitySkill
- deep-researchSkill
- dogfood-cliSkill
- enforce-rules-formatSkill
- generate-logoSkill
- hexagonal-architectureSkill
- landing-siteSkill
- pr-to-lint-ruleSkill
- screenshotSkill
- ship-a-featureSkill
- verify-docs-findableSkill
- pr-to-lint-ruleSkill
- adopt-specSkill
- debug-my-harnessSkill
- edit-specSkill
- linter-docsSkill
- strengthenSkill
- test-harnessSkill
The file
We split this skill into the rules it gives an agent
4 rules. 0 are common, 3 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 21 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
Read the doc in full and skim the docs it links to (so "promises depth the linked doc doesn't deliver" is checkable).
- Very specific: line 53
Run all of these unless the user scopes to a subset.
- Distinctive: line 86
If the user asks to "get it to N/5" (or "until 5/5"): apply the highest-leverage fixes yourself, then re-fan-out (resume the same subagents …
- Distinctive: line 111
Keep the synthesis scannable and ACTIONABLE: every finding names a line and a fix.
“Common” is measured: kept by at least 6 in 10 of the 21 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Review a front-door doc (default README.md; honor a path the user names) the way
real readers would — not the way the author does. The author knows what every line
means; a first-time reader does not. The job is to surface where a specific audience
gets confused, under-served, or bounces, score it, and propose concrete fixes.
The method is fan-out: spawn one subagent PER PERSONA, all in parallel, each doing a cold read as that reader. Different readers catch different things; running them concurrently is faster and keeps each read uncontaminated by the others.
How to run it
1. Read the target doc yourself first
Read the doc in full and skim the docs it links to (so "promises depth the linked doc doesn't deliver" is checkable). You need this to judge the personas' findings and to apply fixes later.
2. Fan out one subagent per persona — in parallel
Spawn the personas below as subagents in a single message (multiple Agent/Task calls at once) so they run concurrently. Use a fast, cheap model (Sonnet or Haiku) — this is a reading/judgment task, not heavy synthesis — and say so in one line when you launch them.
Give EACH subagent the same rubric, only the persona changes:
You are <PERSONA>. Read
<path>(ignore any HTML comment block at the top — that's internal authoring notes, not user-facing copy). Do a COLD read as this reader: adopt their goals, vocabulary, and patience. Be a harsh grader — most READMEs are a 3; 5/5 means you'd genuinely act on it and it's crisp end to end. Return ONLY:
- SCORE: x/5
- 30-second test: after the first screen only, in one sentence, what do you think this tool does — and is that right/wrong/fuzzy?
- Top 3 concrete problems — each quotes the exact line/phrase and gives a specific suggested rewrite (confusing jargon, sentences carrying too many ideas, anything that doesn't sell, formatting that hurts scanning, hype that costs trust).
- Jargon check: every word you had to stop on (harness, spec, eval, subagent, rings, recall/precision…) — is it defined in context or left guessing?
- What works — keep these, so revisions don't lose them.
- The one change that would move the score most. Quote exact text. Be useful, not polite.
3. The personas (the fan-out set)
Run all of these unless the user scopes to a subset. Edit the set freely for a given doc — these are the default readers of vigiles's front door.
- Claude Code newcomer — new to agentic tooling, bounces on undefined terms. Needs a clear "what do I do first," not theory. Catches jargon used before it's defined.
- Claude Code power user — lives in CC, skimming on a phone between tasks. Wants the WOW in the first screen and a copy-paste install in seconds; allergic to fluff.
- Plugin / skill author — mid-level dev, comfortable with TS but not a rule-enforcer/types nerd. Found this because it claims to test their skills. Cares about "does it work on MY repo without learning a new theory?"
- Skeptical senior / staff engineer — scans for substance in ~20s, mentally compares to promptfoo / ESLint / ast-grep. Anything hand-wavy or overclaimed costs trust; every load-bearing claim should link proof.
- Decision-maker (won't run a command) — deciding whether the team adopts. Cares about cost, risk, effort; needs the "free deterministic vs. metered per-token" story and the low-risk incremental on-ramp to be legible without running anything.
- Codex user (optional) — uses
AGENTS.md, not Claude Code. Skeptical this is "a Claude-only thing." Is Codex support visible early or buried/footnoted?
4. Synthesize
Collect the scores and reports. Then:
- Cross-cutting issues first. The 2–4 problems that hurt MULTIPLE personas are the highest-leverage fixes — lead with those.
- Lowest score is the ceiling. The doc is only as good as its weakest reader's read; name what's blocking that persona.
- Produce a ranked fix list — highest reader-impact first, each a one-line action quoting the line and the fix.
5. Iterate to a target (only when asked)
If the user asks to "get it to N/5" (or "until 5/5"): apply the highest-leverage fixes yourself, then re-fan-out (resume the same subagents with the change list, or spawn fresh) and collect new scores. Repeat until every persona is at the target or scores stop moving. Bound it — if a round produces no improvement, or after ~3 rounds, stop and report what's blocking the last point rather than churning. By default this skill REPORTS; only enter the apply-and-iterate loop on an explicit "fix it / get it to N/5".
Output format
# Doc review — <file>
## Scores
<persona> — x/5 (one-line verdict each)
## Cross-cutting issues (highest leverage)
The 2–4 problems hitting multiple personas, each with the line + the fix.
## Per-persona highlights
The sharpest single finding from each reader (don't dump the full reports).
## Ranked fixes
Ordered, highest reader-impact first — each a one-line action.Keep the synthesis scannable and ACTIONABLE: every finding names a line and a fix. Hold the doc to its own standards while reviewing — for the README that's the front-door brevity bar (lead with benefits, one idea per sentence, define jargon at first use, push depth into linked docs). Don't rewrite the doc in place unless the user asks for the iterate loop — this skill REPORTS by default.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

