re0-readme

使用随附的脚本审查代码仓库的 README、AGENTS.md 和清单文件，然后移动、改写或保留每条标记的行，使其位于需要它的读者所对应的文件中，并修正与代码仓库不一致的清单。

目标

README.md 面向正在决定是否使用以及如何使用该代码仓库的人。AGENTS.md 面向在其中工作的 Agent：目录结构、命令、门禁和约定。每一行都应放在需要它的读者所对应的文件中。两类读者都需要的事实，应分别以适合各自读者的形式呈现（人打开的地址放在 README 中，Agent 维护的配置放在 AGENTS.md 中）；两个文件都不重复对方的操作流程，而是相互链接，不复制内容。主机或注册表在打开这两个文件之前展示的清单（package.json、.claude-plugin/ 和 .codex-plugin/ 插件文件、市场清单文件、每个技能的 agents/openai.yaml）应使用代码仓库统一的名称，指向代码仓库自身的地址，并准确列出它所包含的技能文件夹。因此，若重命名只改了 README，却没有更新清单，那么所有列出该项目的主机上仍会显示旧名称。

触发条件：README 或 AGENTS.md 即将编写、刚刚编写完毕或正在审查，或者其中一行被怀疑是写给另一个文件的读者看的。输入是代码仓库根目录（请求所针对的代码仓库；如果未指定，则使用当前工作目录对应的代码仓库），还可选择指定类型、额外的本地状态文件夹名称，以及本次运行是否可以重写文件或只能报告问题。

每次运行都必须报告基线审计结果、审计类型和来源，以及每个发现项的规则 ID、文件、行号和严重级别，并附上说明保留理由的保留清单。仅审查模式会报告建议的移动，然后停止，不进行编辑、后续审计或托管审计。若审计已通过，则报告基线并保持不变后停止。重写模式会报告已编辑的文件、后续审计结果，以及托管审计结果或其未解决的失败。

当基线审计通过时，应审查每个发现项和计划进行的更改，包括清单修正；只有在没有任何内容需要处理时，才保持不变并停止。零项编辑也算成功运行。

工作流程

1. 任何编辑之前先运行审计，并保留其输出作为基线。从此技能所在的文件夹运行：

   node scripts/audit.mjs [<repo-root>] [--kind app|cli|library|skills] [--loop-dir <name>]... [--host <owner/repo>] [--strict] [--json] [--rules]
   

   它会按文件、行号和规则 ID 排序，并报告每项发现的规则 ID、文件、行号和严重程度。--json 会将结果打印为一个 JSON 对象；--rules 会按类别打印每个规则 ID 及其严重程度。退出代码：0 表示没有 fail 级发现；1 表示存在 fail 级发现、--strict 下存在任何发现，或缺少 AGENTS.md；2 表示用法错误或输入无法读取（未知类别、根路径不是目录、package.json 无法解析）。退出代码为 2 表示运行失败，绝不是审计不通过：修正命令或输入后重新运行。如果只有 CLAUDE.md，则将其作为 Agent 指南读取，并报告缺少 AGENTS.md 这一失败；重写时可以创建 AGENTS.md，将其作为指南，或将其链接到 CLAUDE.md，然后重新运行审计。审查只会提出这项修复建议，不会写入文件。

2. 检查类别。 除非指定了 --kind，否则会根据仓库文件检测类别；请将其与仓库实际提供的内容进行比对，若检测有误，则传入 --kind。仓库自身的 .gitignore 排除的点号开头文件夹会被视为本地状态；每次使用 --loop-dir 都会额外添加一个名称，因此，对于 .gitignore 未列出的本地状态文件夹，请传入该参数。类别决定严重程度：对于 CLI，命令属于产品界面；对于技能目录，Agent 词汇是其主题；对于应用，图片属于产品内容。

3. 结合上下文阅读每项发现。 匹配结果只是线索，绝非定论：故障排查变量可以放在 README 中，贡献者的测试命令也可以保留为说明。对每项发现决定是移动、重写还是保留，并将每项保留的理由写入保留清单；该清单应放在报告中，而非文件中。如果某项事实除了按读者区分的两种表述外，还同时复制到了两个文件或第三份文档中，请调用 Skill 工具并使用 "ssotize"（paperthin:ssotize）。

4. 收到审查请求时到此为止。 对于审查、审计或检查请求，应报告基线、针对每项发现提出的移动建议及保留清单，不做任何编辑。只有在请求是编写、修复或重写文件时才继续。

5. 面向 README 的读者重写 README，使用该读者所用的语言；语言由仓库所有者或同级仓库决定，而不是由代码所用语言决定：开篇用一句话说明产品是什么，接着说明按实际衡量结果来看它目前能做什么，然后给出可见结果或用法示例、最简可用设置、支持的环境、重要依赖项，以及更详细文档的链接。如果产品目前的功能少于其设计目标，应在靠近顶部的位置说明这一点，并附上衡量结果；设计目标只能作为目标说明，否则读者会被误导，以为该文件描述的是产品现状。在列表表格中，将分组列改为分节，用图标和文字标注状态，并且只提供一次图例。仅在有助于用户使用或参与贡献时保留操作细节。如果 README 中的技术栈、供应商或工具名称代表某种机制，请调用 Skill 工具并使用 "detool"（paperthin:detool）。

6. 对于视觉产品，将真实产品图片放在长篇说明之前。 等场景中的字体、图片和数据加载完毕后再逐张截图，并在发布前检查画面。从产品可在手机或其他设备上运行之日起，就应在桌面屏幕旁展示这些设备的屏幕，并使用仓库脚本和已提交的示例数据进行截图。图片尺寸和文件夹遵循仓库约定。

7. 面向 AGENTS.md 的读者重写 AGENTS.md，即面向 Agent；除非仓库约定指定了其他语言，否则使用英语。面向韩语读者的 README 并不意味着 AGENTS.md 也要改成韩语。开篇说明哪份文档负责哪类事实，接着介绍仓库结构、运行命令、各检查关卡及其保护内容、附有依据的失败规则、文档约定和提交约定。所有者表格之后，调用 Skill 工具并使用 "re0-order"（paperthin:re0-order），将章节和列表调整为统一的明确顺序。检查强制执行的规则要在旁边注明对应检查，方便 Agent 执行；有衡量数据的情况应以一句证据说明，面向人的解释则移至 README。保留原始语言的契约和证据链接，不要翻译。如果任一文件内容过度膨胀，超出其承载信息的密度，请调用 Skill 工具并使用 "debloat"（paperthin:debloat）。

8. 对齐审计指出的清单文件：每个清单都填写仓库名称（npm 名称须使用小写形式），每个地址都指向仓库自身的源地址；列出插件所提供的所有技能文件夹，且不得包含其他内容；并为每项技能提供一个 agents/openai.yaml，其默认提示词应包含 $<skill>。若清单由仓库生成，则应在其生成器中修复。

9. 重新运行审计，并从各自预期读者的角度阅读这两份文件和清单文件。

10. 审计托管平台上的页面，运行 node scripts/audit.mjs --host <owner/repo>。检查描述是否与 README 开篇及其所述内容一致、主题标签、主页权威性、社区资料缺失项、README 长度，以及设置了自定义社交预览图时的尺寸和适用性。托管平台审计只报告问题：请针对其发现提出修正建议。若某设置以一项收益换取一项损失，则会作为选项打印出来，而非发现，且不会导致运行失败：不设置自定义社交预览图时，GitHub 会使用默认卡片，并实时显示星标、复刻和贡献者，因此报告会告知所有者可以更改设置，并将选择权留给他们。

11. 品评重写内容：在审批前停止之前，调用 Skill 工具并使用 "sip"（paperthin:sip）。

12. 提出检查关卡，然后到此为止。 如果仓库维护检查关卡列表，请提议将审计作为脚本的仓库内副本添加到列表中，并用注释注明来源，这样检查关卡在全新克隆的仓库中也能运行；绝不要让检查关卡指向仅存在于某台机器上的路径。由人工决定；未经批准，不得将任何内容添加到检查关卡列表或 CI 中。

规则

• 如果宿主没有 Skill 工具，直接阅读并遵循每项已安装且具名的技能；如果技能不可用，报告缺失的步骤，不要声称已运行。
• 规则表由脚本负责。说明脚本名称、其标志和退出代码，绝不要重述规则；--rules 会打印规则。
• 解释不会改变退出代码。接受的说明无需 --strict 也可以通过；保留的失败项仍会标红。修正类型；有充分理由时，提议修改仓库中该规则的副本；否则报告门禁尚未解决。绝不要声称通过一段说明获得了例外。
• 移动内容时不得丢失任何信息：从一个文件移出的行必须放到另一个文件、链接的文档，或附有原因的保留清单中。彻底删除一项事实需要获得人工批准。
• 审查请求只需报告。只有请求编写、修复或重写文件时才进行重写。
• 安全编辑：替换前确认每个目标行都存在，并报告 MISS；使用 Unicode 安全的方式编辑，逐个匹配项处理，绝不进行批量替换。
• 合约、台账、变更日志和发行说明不在范围内。
• 三项变更须等待人工明确批准；在批准前，运行报告必须将每项变更列为提案：将审计纳入仓库门禁清单或 CI（步骤 12）；删除没有其他存放位置的事实；修改脚本在仓库中 vendored 的副本中的规则。

验证

完成前，确认：

1. 每份报告都包含基线和类型来源；重写还必须包含审计后的结果和托管平台的结果，而审查或已通过的运行则在其说明的退出状态处结束。
2. 每项发现都已移动、重写，或附有原因予以保留；审查中提出了处置方案也可。不得通过解释将任何失败项报告为已通过。
3. 没有事实丢失：每一条移动的行都能在新位置找到。
4. 对于重写，README 须以介绍产品内容开篇，Agent 指南须以说明各文档的职责开篇。
5. 对于重写，README 须以读者所使用的语言说明根据测量结果，产品当前能做什么；托管平台上的描述也须表述相同内容，否则应提议新增相应内容。
6. 任何门禁变更都须等待批准，并在报告中列出所有仍待批准的事项。