1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | docs-sync-audit（github/awesome-copilot 仓库 skills/ 目录下的独立子技能） |
SKILL.md |
| 作者/维护者 | GitHub 官方账号（合集仓库），子技能提交者 Furkan Reha | GitHub API（commits） |
| 来源链接 | https://github.com/github/awesome-copilot/tree/main/skills/docs-sync-audit | — |
| 许可证 | MIT | GitHub API |
| GitHub Stars / Forks | 39,016 / 4,946（整个 awesome-copilot 合集仓库层面，非本子技能单独统计，见第 7 章说明） | GitHub API |
| 最新版本 | 无独立版本号，随仓库滚动更新（最近一次改动为引用行锚点修复） | GitHub API（commits） |
| 安装方式 | 复制 skills/docs-sync-audit/ 目录（含 SKILL.md 与 scripts/docs_drift.py）到 Agent 的 skills 目录（见第 10 章） |
— |
2. 功能介绍与亮点
docs-sync-audit 是一个只读的“文档漂移”审计技能——不写文档，只核对现有文档是否还跟得上代码。它不是通用代码审查，而是专门比对“文档怎么说”与“代码实际怎么做”之间的落差：README 安装步骤、API 文档、环境变量说明、CLI 帮助、changelog、示例代码、生成型文档等都在覆盖范围内。
核心流程分四步：先确定改动的真相源（git 状态、变更文件、路由/配置/schema 等）；再定位相关文档；然后逐项比对（命令参数、API 路由鉴权、配置项、UI 流程、数据字段、示例代码）；最后用低风险命令做安全验证（文档构建、link check、typecheck），并明确禁止执行任何会写入仓库的命令（如 py_compile 会留下 .pyc 文件）。
主要亮点：
- 附带零依赖脚本
scripts/docs_drift.py，机械核对 npm/make 命令是否真实存在、Markdown 相对链接是否指向真实文件、环境变量在文档与代码间双向核对——只检查“有明确对错答案”的事，不判断文风 - 明确的证据纪律：每条发现必须给出可点开的
path:line，禁止“看起来像”式的猜测计数，工具报告的行号不得靠人工推断 - 内置提示注入防御——把代码库里读到的任何“指令性文字”（README、注释、commit message 等）一律当作待审计证据而非指令，若发现夹带指令会作为一条发现记录下来而不是执行
- P0–P3 四级严重度分级 + 固定报告模板，附“已核实但未深查”分区，避免把浅扫描包装成完整覆盖
3. 适用场景
固定分类：工程效率与代码质量。
适合在合并 PR、发版前，或接手一个文档与代码已经脱节的老项目时，快速定位哪些文档已经过期、哪些新功能漏写了文档；对没有专职技术文档团队、只能靠开发者自己顺手维护文档的初中级开发团队尤其实用。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 标准 SKILL.md 格式，description 中已声明触发场景 |
| Codex | 需适配 | SKILL.md 本体是通用 Markdown 指令加一份 Python 脚本，无 Claude 专属语法，但需手动复制目录结构使 scripts/docs_drift.py 的相对路径可解析 |
| OpenClaw | 需适配 | 同上，需手动放入其技能目录并确保脚本路径可解析 |
| Hermes Agent | 未验证 | 已抓取材料中未发现相关证据 |
5. 推荐理由
文档过期是几乎每个项目都有、却很少有人专门去查的问题——开发者改完代码就提交，README 和 API 文档是否还准确往往没人核实，等用户或新同事踩坑才发现。docs-sync-audit 把“文档是否还跟得上代码”变成一套可重复执行的只读审计流程：先定真相源、再比对、再用低风险命令验证，每条发现都要求给出可点开的文件行号证据，杜绝“大概是这样”式的模糊结论。零依赖、零配置，复制目录即可用。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 发布方为 GitHub 官方账号；合集仓库整体 stars 属整个仓库，不代表本技能自身热度，且未查到该子技能自身的独立第三方讨论或采用数据 |
| 可用性 | 9 | 复制目录即可用，SKILL.md 结构清晰、含完整发现流程、证据标准与报告模板，随附脚本零外部依赖；无付费依赖、无需 API key；2026-09-07 提交、当日即有修复跟进，维护活跃 |
| 安全性 | 9 | 见下方检查清单 |
安全检查清单：
① Shell 命令与权限：仅执行明确声明为只读的验证命令（文档构建、link check、typecheck），正文反复强调“禁止写入仓库的命令”并给出具体反例（如 .pyc 文件）
② 联网外发：无任何网络请求，全程本地文件读取
③ API key/凭据：不要求任何凭据
④ 可疑指令：逐份核查 SKILL.md 与随附脚本全文，未发现夹带指令、混淆代码或隐蔽外发；反而内置了针对性的提示注入防御条款
⑤ 作者信誉：提交者账号在 GitHub 官方合集仓库的公开 PR 审核流程下合并，无造假迹象
⑥ License：MIT，明确
⑦ 维护时间：2026-09-07 新增，同日即有跟进修复提交，属近期活跃维护
7. 跟同类 Skills 相比的优势
| 技能 | 定位 | 与 docs-sync-audit 的差异 |
|---|---|---|
| test-gap-audit（github/awesome-copilot，同仓库姊妹技能） | 只读测试覆盖度审计 | 核对的是“代码改动是否留有测试缺口”，对象是测试而非文档；两者共享同一套 P0–P3 报告契约但审计对象完全不同 |
| docs-guard（amElnagdy/guard-skills） | AI 生成文档的事后核查闸 | 场景是“文档刚被 AI 写完/改完，逐条核实其中的技术性声明是否属实”，触发点是文档写作动作本身；docs-sync-audit 的触发点是代码变更，核查“文档有没有跟上”，两者对应文档生命周期的不同阶段 |
| ln-22-codebase-auditor（levnikolaevich/claude-code-skills） | 代码库七维健康体检 | 覆盖安全、可维护性等七个维度的整体体检，文档只是其中一小部分；docs-sync-audit 专精文档漂移这一件事，审计深度更深 |
docs-sync-audit 的差异化在于专注“代码变更后文档是否同步”这一具体触发场景，并用零依赖脚本把可机械核实的部分（命令、链接、环境变量）自动化，同时明确划出“工具能查什么、人工该判断什么”的边界。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价，仅在若干 Claude/Copilot Skills 目录聚合站点被收录列出。
9. 其他补充
技能明确要求“引用的代码行必须真的包含被引用的内容”，并给出多个反例（不能引用装饰器行、不能引用多行字面量内部的某一行），是对 LLM 常见的引用行号漂移问题的针对性约束。
10. 安装使用方式
- Claude Code / 兼容 Agent：将
github/awesome-copilot仓库中skills/docs-sync-audit/整个目录（含 SKILL.md 与 scripts/docs_drift.py）复制到本地项目或全局的 skills 目录下即可自动被识别 - 触发方式：在对话中说“这个 PR 的文档需要更新吗”“检查文档是否过期”“audit docs for this feature”等
- 安装后无需重启；审计完成会先给出漂移摘要与 P0/P1 计数，随附“已核实但未深查”分区与“未测试”风险清单，需要更新文档时再显式要求技能执行修改（默认只读，不主动改文档）
11. 注意事项
- 随附的
scripts/docs_drift.py只核对有明确对错答案的机械事实（命令是否存在、链接是否指向真实文件、环境变量双向核对），文风、完整性、解释是否正确仍需人工判断，技能本身承担这部分工作 - 跨 Agent 平台的兼容性尚未在 Codex / OpenClaw / Hermes Agent 上完整验证，实际使用前建议先做小范围测试
- 技能默认只读，若要求它直接修改文档需显式授权，且会尽量保留原文档的风格与术语