关于 doc-cleanup
doc-cleanup 是一项用于诊断和清理过时或矛盾 Markdown 指引的技能，同时保留重要规则与历史记录。它要求先基于仓库证据提交报告并取得用户批准，再执行修改和验证。
主要功能
- 01盘点 Markdown 文件
- 02识别过时及矛盾内容
- 03依据仓库证据核对文档
- 04提出最小安全改动
- 05保留重要规则与历史
- 06验证修改和链接
适用场景
- 01审查 Agent 指引中的过时内容
- 02处理项目文档之间的矛盾
- 03清理已完成的计划和日志
- 04评估文档清理方案
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/doc-cleanup确认已加载。
详细介绍
文档清理
清除 Markdown 中的上下文腐化内容，但不要抹去关键规则或有用的历史信息。将每项文档声明都视为假设，并以代码仓库为依据。
分两轮进行：先诊断并报告，不做编辑；只有用户批准拟议的清理方案后，才开始执行。获准编辑不代表获准提交。
1. 清点完整范围
列出所有范围内的 *.md 文件，排除生成文件、依赖项、版本控制和用户排除的路径。记录每个文件的行数和角色：
- 入口：
AGENTS.md、CLAUDE.md或同等文件 - 必读：入口文档要求 Agent 阅读的文件
- 参考：有条件查阅的文件
- 历史：保留供查阅，不作为当前指导的文件
遵循每份入口文档中的阅读指引。根据阅读频率评估问题：必读文档中的腐化内容，比档案中的同类问题影响更大。
只有在每个范围内的 Markdown 文件都有角色，且每条入口文档的阅读指引都已标记为已解析、失效或外部，清点工作才算完成。
2. 诊断，不做编辑
深入阅读每份范围内的文档，以检查以下腐化模式：
- 已完成工作的日志 — 已完成的检查清单、阶段日志、实现过程叙述、复盘和验证记录，却被当作当前指导。
- 已执行的计划 — 已发布的计划仍以意图表述，包括已被取代的分析和被否决的选项。
- 内部矛盾 — 相互冲突的值、过时表格下方的更正，或推翻早期指导的日期附录。
- 过时声明 — 指向已重命名符号、已更改常量、错误行号的引用，或声称已合并的工作尚未合并。
- 失效路径 — 缺失文件、过时的机器路径、已迁移的代码仓库或已移除的工具。
- 权威漂移 — 声称是事实来源的内容已不再符合实现行为或后续权威决策。
对每个疑似问题，记录：
- 精确的文件和行号
- 有问题的声明或内容
- 来自文件查找、搜索、配置、测试或 Git 历史的仓库证据
- 置信度及任何尚未解决的歧义
- 最小且安全的处理方式：保留、更正、精简、归档或添加提示标记
代码能证明已实现的行为，但未必能证明预期行为。如果文档可能定义了预期契约，应将不一致报告为尚未解决的权威漂移，除非仓库证据能确定哪项权威内容已取代另一项。
标记必须保留的关键内容：硬性规则、当前有效的决策、反复出现的陷阱、操作指导和领域词汇。即使发现陷阱的经过已成为历史，该陷阱本身仍可能有效。
只有在每份已清点的文件至少有一项有证据支持的发现，或被明确标记为无问题，且每项事实性发现都已依据仓库证据核查后，诊断才算完成。
3. 报告并停止
按「阅读频率 × 误导风险」从高到低列出发现。针对每项发现，说明问题声明、证据、影响和拟议处理方式。然后给出逐文件清理计划，并单独列出尚未解决的决策，说明哪些关键内容会保留。
等待批准。诊断阶段必须保持工作区不变。
只有当用户无需额外调查，就能批准、拒绝或修改每项拟议的文件变更时，报告才算完成。
4. 执行已批准的计划
写下每项事实性声明前，都要立即重新核查。仅应用已批准的更改，并按以下逐文件操作指南执行：
- 归档必须便于查阅的历史内容。 在
docs/archive/中放入原文副本或边界明确的摘录，并使用具有抗冲突能力的来源和日期名称。将其来源路径以及 Git blob 或内容哈希记录在清理报告或旁置清单中，保持原文内容不变。将完整文件归档与编辑前留存的源文件进行核验；将摘录与记录的来源范围进行核验。如果无需在线归档也能方便查阅，Git 历史记录本身就足够。 - 将当前指南改写为最新事实。 如果创建了归档，添加简短的归档指引。每项保留的事实性声明都必须以当前证据为依据，不得未经核查就沿用。
- 指向权威来源。 指明负责维护的架构、配置或源文件，而不是重复易变的值。
- 精简已完成的工作。 将已完成的检查清单替换为简短的结果说明；保留未完成事项的原文措辞。
- 保留易错点。 将反复出现的陷阱改写为简短的祈使式指南，再迁移其历史叙述。
- 标明尚未解决的偏差。 说明不一致之处和当前生效的权威依据；如果所有权尚不明确，不要暗中改写契约。
- 修复入口文档。 修正失效的阅读指引和过时的功能声明，并尽量缩减必读文档列表。
只有在每项已批准的发现都有对应的差异，或有记录说明无需更改，并且改写涉及的每项保留事实性声明都有最新证据时，执行才算完成。
5. 验证并交接
请验证以下事项：
- 每个已修改文件中的相对链接都能正常解析
- 完整文件归档与其编辑前留存的源文件逐字节一致，摘录与记录的来源范围一致
- 诊断期间确认的关键内容仍保留在当前指南中
- 差异中仅包含已批准的 Markdown 更改
- 已修改的文档之间没有引入新的矛盾
报告已更改文件、归档映射、已纠正的矛盾、尚未解决的权威依据决策，以及已执行的验证。提出一个仅包含文档更改、附带具体提交信息的提交方案；只有在用户授权提交后才创建提交。
只有在每项已批准的发现都有交代、所有检查均已通过，并且用户拿到可供审阅的差异及任何待决事项时，清理才算完成。