# Review Docs > 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,… - **Type:** Skill - **Install:** `agentstack add skill-zernie-vigiles-review-docs` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [zernie](https://agentstack.voostack.com/s/zernie) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [zernie](https://github.com/zernie) - **Source:** https://github.com/zernie/vigiles/tree/main/.claude/skills/review-docs - **Website:** https://vigiles.sh ## Install ```sh agentstack add skill-zernie-vigiles-review-docs ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About 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 **\**. Read `` (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: > > 1. **SCORE: x/5** > 2. **30-second test:** after the first screen only, in one sentence, what do you > think this tool does — and is that right/wrong/fuzzy? > 3. **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). > 4. **Jargon check:** every word you had to stop on (harness, spec, eval, subagent, > rings, recall/precision…) — is it defined in context or left guessing? > 5. **What works** — keep these, so revisions don't lose them. > 6. **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. 1. **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. 2. **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. 3. **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?" 4. **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. 5. **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. 6. **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 — ## Scores — 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. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [zernie](https://github.com/zernie) - **Source:** [zernie/vigiles](https://github.com/zernie/vigiles) - **License:** MIT - **Homepage:** https://vigiles.sh 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-zernie-vigiles-review-docs - Seller: https://agentstack.voostack.com/s/zernie - 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%.