/SKILL.md

name, description

name	description
doc-maintenance	审计顶层文档（README、SPEC、PRODUCT）与近期 Git 历史之间是否存在漂移——已发布的功能在文档中缺失，或文档列为"即将推出"的功能实际上已上线。提出最小修改建议，创建分支，并提交 PR。适用于被要求审核文档准确性时、重大功能合并后，或按周期执行。

文档维护技能

发现文档漂移并通过 PR 修复——不重写，不折腾。

适用场景

• 定期文档审核（例如每周或发布后）
• 重大功能合并后
• 被问及"我们的文档是否最新？"时
• 被要求审核 README / SPEC / PRODUCT 的准确性时

目标文档

文档	路径	关注要点
README	README.md	功能表、路线图、快速入门、"这是什么"的准确性、"可与以下工具配合使用"的表格
SPEC	doc/SPEC.md	没有错误的"不支持"声明，主要模型/模式的准确性
PRODUCT	doc/PRODUCT.md	核心概念、功能列表、原则的准确性

不在范围内：DEVELOPING.md、DATABASE.md、CLI.md、doc/plans/、技能文件、发布说明。这些是面向开发者或临时性的文档——造成用户混淆的风险较低。

工作流程

步骤 1 — 检测变更内容

找到上一次审核的光标位置：

# 读取上一次审核的提交 SHA
CURSOR_FILE=".doc-review-cursor"
if [ -f "$CURSOR_FILE" ]; then
  LAST_SHA=$(cat "$CURSOR_FILE" | head -1)
else
  # 首次运行：回溯 60 天
  LAST_SHA=$(git log --format="%H" --after="60 days ago" --reverse | head -1)
fi

然后收集光标位置之后的提交：

git log "$LAST_SHA"..HEAD --oneline --no-merges

步骤 2 — 对变更分类

扫描提交消息和变更文件。归类为：

• Feature（新功能）—— 新的能力（关键词：feat、add、implement、support）
• Breaking（破坏性变更）—— 移除/重命名的内容（关键词：remove、breaking、drop、rename）
• Structural（结构性变更）—— 新目录、配置变更、新适配器、新 CLI 命令

忽略： 重构、仅测试变更、CI 配置、依赖版本更新、仅文档变更、样式/格式化提交。这些不影响文档准确性。

对于边界情况，检查实际的 diff——标题为"refactor: X"但新增了公开 API 的提交属于功能变更。

步骤 3 — 构建变更摘要

生成简洁列表，例如：

自上次审核（<sha>，<date>）以来的变更：
- FEATURE（新功能）：插件系统已合并（运行时、SDK、CLI、插槽、事件桥接）
- FEATURE（新功能）：新增项目归档功能
- BREAKING（破坏性变更）：移除了旧版 Webhook 适配器
- STRUCTURAL（结构性变更）：新增 .agents/skills/ 目录约定

如果没有值得注意的变更，直接跳到步骤 7（更新光标位置并退出）。

步骤 4 — 审核每个目标文档

针对每个目标文档，完整阅读并与变更摘要进行交叉核对。检查以下内容：

1. 假阴性——已发布的重要功能在文档中完全没有提及
2. 假阳性——列为"即将推出"/"路线图"/"规划中"/"不支持"/"待定"但实际已上线的功能
3. 快速入门准确性——安装命令、前置条件和启动说明是否仍然正确（仅 README）
4. 功能表准确性——功能部分是否反映了当前的能力？（仅 README）
5. "可与以下工具配合使用"的准确性——支持的适配器/集成是否列正确？

使用 references/audit-checklist.md 作为结构化检查清单。 使用 references/section-map.md 了解每个功能区域的位置。

步骤 5 — 创建分支并应用最小修改

# 为文档更新创建分支
BRANCH="docs/maintenance-$(date +%Y%m%d)"
git checkout -b "$BRANCH"

仅应用修复漂移所需的修改。规则：

• 仅做最小修补。 修复不准确之处，不要重写章节。
• 保留语气和风格。 与每个文档的现有语气保持一致。
• 不做外观性修改。 除非是事实性修复的一部分，否则不要修正拼写错误、重新格式化表格或重新组织章节。
• 不新增章节。 如果一个功能需要全新的章节，在 PR 描述中将其标注为后续事项——不要在维护性检查中新增。
• 路线图条目： 将已发布的功能移出路线图。在适当的现有章节中添加简要提及（如果还没有的话）。不要添加冗长的描述。

步骤 6 — 提交 PR

提交变更并打开 PR：

git add README.md doc/SPEC.md doc/PRODUCT.md .doc-review-cursor
git commit -m "docs: update documentation for accuracy

- [简要列出每个修复项]

Co-Authored-By: Paperclip <noreply@paperclip.ing>"

git push -u origin "$BRANCH"

gh pr create \
  --title "docs: periodic documentation accuracy update" \
  --body "$(cat <<'EOF'
## Summary
Automated doc maintenance pass. Fixes documentation drift detected since
last review.

### Changes
- [list each fix]

### Change summary (since last review)
- [list notable code changes that triggered doc updates]

## Review notes
- Only factual accuracy fixes — no style/cosmetic changes
- Preserves existing voice and structure
- Larger doc additions (new sections, tutorials) noted as follow-ups

🤖 Generated by doc-maintenance skill
EOF
)"

步骤 7 — 更新光标位置

在成功完成审核后（无论是否进行了修改），更新光标位置：

git rev-parse HEAD > .doc-review-cursor

如果进行了修改，该操作已在 PR 分支中提交。如果不需要修改，则将光标位置更新提交到当前分支。

变更分类规则

信号	类别	是否需要更新文档？
消息中包含 feat:、add、implement、support	Feature（新功能）	是，如果面向用户
消息中包含 remove、drop、breaking、!:	Breaking（破坏性变更）	是
新增顶层目录或配置文件	Structural（结构性变更）	可能
fix:、bugfix	Fix（修复）	否（除非改变了文档中描述的行为）
refactor:、chore:、ci:、test:	Maintenance（维护）	否
docs:	Doc change（文档变更）	否（已处理）
仅依赖版本更新	Maintenance（维护）	否

修补风格指南

• 修复事实，而非文笔
• 如果移除路线图条目，不要留空——干净地删除该条目
• 如果添加功能提及，与周围条目的格式保持一致（例如，如果功能以表格形式呈现，则添加一行表格行）
• 对 README 的修改尤其要精简——它不应频繁变动
• 对于 SPEC/PRODUCT，优先更新现有语句而非新增语句（例如，将"V1 中不支持"改为"通过 X 支持"，而不是新增一个章节）

输出

技能完成后，报告以下内容：

• 扫描了多少个提交
• 找到了多少个值得注意的变更
• 做了多少次文档修改（以及修改了哪些文件）
• PR 链接（如果进行了修改）
• 任何需要更大文档工作的后续事项