review-docs

像真实读者那样评审入口文档（默认为 README.md；遵循用户指定的路径），而不是像作者那样评审。作者知道每一行的含义；初次阅读者并不知道。任务是找出特定受众会在哪里感到困惑、得不到所需信息或放弃阅读，为文档打分，并提出具体的改进方案。

方法是扇出：每种人物画像启动一个子 Agent，所有子 Agent 并行进行，各自以该读者的视角冷读。不同读者会发现不同问题；并行运行更快，也能避免彼此的阅读受到影响。

如何执行

1. 先自行阅读目标文档

通读文档，并浏览其中链接到的文档（这样才能检查“承诺的深入内容是否确实由链接文档提供”）。你需要先了解这些内容，才能判断各人物画像的发现，并在之后应用改进。

2. 为每种人物画像启动一个子 Agent，并行运行

在同一条消息中启动下列人物画像的子 Agent（一次调用多个 Agent/Task），让它们并行运行。使用快速、低成本的模型（Sonnet 或 Haiku）——这是阅读和判断任务，不需要大量综合分析——启动时用一行说明这一点。

向每个子 Agent 提供相同的评分标准，只更换人物画像：

你是**<PERSONA>**。阅读 <path>（忽略顶部的任何 HTML 注释块——那是内部编写说明，不是面向用户的文案）。以该读者的身份冷读：采用他们的目标、词汇和耐心程度。严格评分——大多数 README 都是 3 分；5/5 表示你真的会据此采取行动，而且全文表达清晰。 仅返回：

1. 评分：x/5
2. **30 秒测试：**只看首屏后，用一句话说明你认为这个工具的用途，以及这个判断是正确、错误还是模糊。
3. 最重要的 3 个具体问题——每项引用准确的原文行或短语，并给出具体的改写建议（令人困惑的行话、承载过多想法的句子、缺乏吸引力的内容、不利于浏览的格式、损害可信度的夸张说法）。
4. **行话检查：**列出所有让你停下来琢磨的词（harness、spec、eval、subagent、rings、recall/precision……）——这些词是否在上下文中得到解释，还是只能靠猜？
5. 有效之处——指出应保留的内容，避免修改时将其丢失。
6. 最能提高评分的一项改动。 引用准确原文。提出有用的建议，不必客气。

3. 人物画像（扇出集合）

除非用户限定了范围，否则运行以下全部画像。针对具体文档，可灵活调整集合——这些是 vigiles 入口文档的默认读者。

1. Claude Code 新手——刚接触 Agent 工具，遇到未定义术语就会放弃。需要清晰的“我该先做什么”，而不是理论。善于发现先用后解释的行话。
2. Claude Code 高级用户——日常使用 CC，任务间隙用手机快速浏览。希望首屏就看到亮点，并能在几秒内复制粘贴安装命令；反感空话。
3. 插件 / 技能作者——中级开发者，熟悉 TS，但不是规则执行器或类型系统专家。因为文档声称能测试他们的技能而找到这个项目。关心的是：“不学一套新理论，这东西能在我的仓库里用吗？”
4. 持怀疑态度的资深 / Staff 工程师——约 20 秒内快速判断内容是否扎实，并会在心里拿它和 promptfoo / ESLint / ast-grep 比较。含糊其辞或夸大其词都会损害信任；所有关键主张都应提供证据链接。
5. 决策者（不会运行命令）——正在决定团队是否采用。关心成本、风险和投入；需要在不运行任何命令的情况下看懂“免费且确定性的检查 vs. 按 Token 计费”，以及低风险、渐进式的入门路径。
6. Codex 用户（可选）——使用 AGENTS.md，而不是 Claude Code。怀疑这是否“只适用于 Claude”。Codex 支持是否很早就能看到，还是被藏在脚注里？

4. 综合分析

汇总评分和报告。然后：

• 优先处理共性问题。 影响多个用户角色的 2–4 个问题，是最值得优先修复的；先列出这些问题。
• 最低分决定上限。 文档的质量取决于体验最差的读者；指出阻碍该角色的因素。
• 提供按优先级排列的修复清单——按对读者的影响从高到低排序，每项用一句话引用原文并说明修复措施。

5. 迭代至目标（仅在用户要求时）

如果用户要求“达到 N/5”（或“直到 5/5”）：自行应用最值得优先处理的修复，然后再次分发评审（让相同的子 Agent 根据修改清单继续评审，或启动新的子 Agent），并收集新评分。重复此过程，直至每个用户角色都达到目标，或评分不再变化。设置上限——如果一轮没有带来改进，或迭代约 3 轮后仍未达标，就停止迭代，并说明最后一点分数受阻的原因，而不是无休止地修改。默认情况下，此技能只会汇报；只有在用户明确要求“修复它 / 达到 N/5”时，才进入应用修复并迭代的流程。

输出格式

# 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.

确保综合分析易于浏览且可执行：每项发现都要指出具体行和修复措施。评审时也要遵循文档自身的标准——对于 README，要达到简洁明了的首页标准（先说明收益，每句话只表达一个观点，首次出现时解释术语，将深入内容放到链接文档中）。除非用户要求进入迭代流程，否则不要直接改写文档；此技能默认只会汇报。