1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | docs-guard（amElnagdy/guard-skills 仓库内子技能，该仓库共含 5 个“guard”系列质量闸技能） |
| 作者/维护者 | Ahmed Nagdy（GitHub 用户 amElnagdy，任职 OnTheGoSystems，GitHub 账号自 2014 年活跃，561 位关注者） |
| 来源链接 | https://github.com/amElnagdy/guard-skills/tree/master/skills/docs-guard |
| 许可证 | MIT（GitHub API 确认） |
| GitHub Stars / Forks | 1,120 / 132（GitHub API，截至 2026-07-30；数字为整个仓库层面，非本子技能单独统计——见第 7 章） |
| 最新版本 | v1.0.0（仓库级标签，2026-06-07 首次发布；本子技能另有 2026-07-04 独立维护提交） |
| 安装方式 | Skills CLI 一条命令安装（见第 10 章） |
2. 功能介绍与亮点
docs-guard 是一个专门针对“AI 生成或修改的文档”场景的第二轮质量闸——不负责写文档，而是在 README、API 参考、docstring、PHPDoc/JSDoc、changelog、教程等文档写完之后，逐条核对每一处技术性表述是否真实。核心问题意识：编码 agent 描述 API 时常凭“通常长什么样”的记忆而非眼前的代码，导致文档读起来权威、实际却包含幻觉——函数名不存在、参数顺序错了、示例代码在真实项目里跑不通。
技能把文档拆成一份“可核查的声明清单”：每一个被提到的函数、CLI 参数、接口路径、配置项、版本号、行为描述，都要求对照源码、CLI 帮助输出或路由表逐条验证，而不是凭印象确认。十条规则分三档——“必须修”（虚假引用、代码示例跑不通、记录意图行为而非真实行为、无来源的量化/兼容性宣称）、“应该修”（版本号未显式标注、代码改了文档没跟着改、空话套话、照抄上游文档、只写正常路径不写报错路径）、“值得留意”（导航结构与死链）。
主要亮点：
- 配套 5 份参考文档，其中
verification.md给出逐类型声明的核查方法（符号核查查定义而非引用、CLI 参数核查解析器注册代码、行为声明追踪实现路径），是可执行的机械流程而非泛泛原则 - 内置“审查前自检清单”与结构化报告模板（声明 / 真实情况 / 修复建议三段式，附 file:line 依据）
- 零依赖、零配置：纯 Markdown 规则文件，不调用外部工具、不需要 API Key，复制即用
- 同一系列还有 4 个姊妹质量闸技能（通用代码审查、测试代码审查、WordPress/WooCommerce 专项审查），风格与规则密度一致，出自同一作者
- 子目录本身有一条独立外部用户提交的文档补充请求（尚未合并），说明已有真实使用者在跟进这个技能
3. 适用场景
固定分类：工程效率与代码质量。
适合频繁让 agent 生成或修改技术文档的开发者——尤其是发现 agent 写的 README 引用了不存在的函数、示例代码复制粘贴后报错、或 changelog 条目对不上实际改动的团队。典型受益人群：需要对外发布 API 文档/SDK 文档的开源维护者，以及在合并前希望有一道自动化“文档准确性闸”的团队。适用于任何语言的 README、API 参考文档、docstring/JSDoc/PHPDoc、changelog 与教程内容。
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持。仓库 README 明确给出
--agent claude-code安装示例，纯 Markdown 规则可直接复制进技能目录使用。 - Codex：✅ 原生支持。README 给出
--agent codex安装示例；docs-guard 目录下另带agents/openai.yaml专属显示配置（展示名称、简介、默认调用提示词），表明作者针对该 agent 格式做过专门适配。 - OpenClaw：✅ 原生支持。仓库通过第三方 Skills CLI（vercel-labs/skills）分发，该 CLI 官方 README 的 Supported Agents 表格明确列出 OpenClaw（标识
openclaw，项目级路径skills/、全局路径~/.openclaw/skills/）。 - Hermes Agent：✅ 原生支持。同一 Skills CLI 的 Supported Agents 表格同时列出 Hermes Agent（标识
hermes-agent，项目级路径.hermes/skills/、全局路径~/.hermes/skills/）。
5. 推荐理由
AI 编码 agent 写文档有一个隐蔽但常见的通病：文档读起来专业、完整、语气笃定，但其中引用的函数签名、CLI 参数、接口路径未必和代码真实一致——读者分辨不出哪句是核实过的、哪句是凭记忆编的。docs-guard 把这种“听起来对”的模糊感变成一套机械的核查流程：把文档拆成声明清单，逐条对照源码验证，给出带 file:line 依据的结构化发现报告。零依赖、零配置，装上就能用，特别适合需要对外发布技术文档、又不想让幻觉内容流出仓库的开发者与小团队。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 6 | 所属 amElnagdy/guard-skills 是合集仓库（5 个子技能共享），仓库整体 1,120 stars/132 forks 不能直接记给本子技能；本子技能自身提交记录仅 2 次（首次发布 + 一次规则修正），另有 1 条独立外部用户提交的文档补充 Pull Request（尚未合并），提交者为普通 GitHub 账号、无法核实企业身份，属真实但偏弱的外部关注证据 |
| 可用性 | 8 | 一条 npx skills add 命令即可安装，支持按技能名或按 agent 单独安装；SKILL.md 含十条规则、自检清单、结构化报告模板；额外配备 5 份参考文档，其中核查方法文档给出逐类型声明的具体核验步骤而非空泛原则；2026-07-04 有维护提交（距今约 26 天），零外部依赖、无需任何 API Key；相比同系列面向通用场景的姊妹技能，本技能聚焦文档这一垂直场景，不含按框架/语言拆分的专属参考 |
| 安全性 | 9 | 全文精读为纯 Markdown 指令文件，不执行任何 shell 命令、不联网外发数据、不要求任何凭据；配套的 agents/openai.yaml 与 5 份参考文档同样是纯文本，未见可疑指令或混淆内容；作者系 OnTheGoSystems 在职工程师，GitHub 账号自 2014 年活跃、561 位关注者，身份可查证；License（MIT）明确 |
综合评分：7.67（三项均值）
安全检查清单： ① shell 命令：否，全程仅输出审查建议文本 ② 联网外发：否 ③ API key/凭据：不需要 ④ 可疑指令迹象：全文精读未发现 ⑤ 作者/组织信誉：Ahmed Nagdy，OnTheGoSystems 在职工程师，GitHub 账号自 2014 年活跃 ⑥ License：MIT，明确 ⑦ 最近维护：2026-07-04（子技能专属修复提交）
7. 跟同类 Skills 相比的优势
| 对比对象 | 定位 | 与本技能的差异 |
|---|---|---|
| documentation-and-adrs（addyosmani/agent-skills 子技能） | 面向“怎么写文档”的方法论指南——覆盖 ADR 全生命周期、行内注释规范、API 文档模板、面向 Agent 的上下文文件（CLAUDE.md 等）四大板块，是撰写时的写作规范 | 定位是“生成规范”而非“核查真实性”，不要求逐条比对源码；docs-guard 只做一件事——文档写完/改完之后，把每条技术性声明拆出来对照代码验证，专治“读起来对但引用不存在的函数”这类幻觉问题，两者可前后配合使用（先按前者的模板写，再用 docs-guard 把关） |
| create-architectural-decision-record（github/awesome-copilot） | GitHub 官方 Community 仓库内的单点技能，只做“生成一份 ADR 文档”这一个动作，面向 GitHub Copilot | 功能范围仅覆盖 ADR 生成，不涉及 README/API 文档/docstring/changelog 等更广的文档面，也不做已有文档的真实性核查；docs-guard 覆盖文档类型更广，且核心动作是核查已产出内容而非生成新内容 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。
9. 其他补充
docs-guard 是 amElnagdy/guard-skills 仓库内 5 个“guard”系列质量闸技能之一，同仓库还含 clean-code-guard（通用代码审查）、test-guard（测试代码质量审查）、wp-guard/woo-guard（WordPress/WooCommerce 专项审查），可按需单独安装或整包安装。
10. 安装使用方式
Skills CLI（推荐，支持 Claude Code / Codex / OpenClaw / Hermes Agent 等）：
npx skills add amElnagdy/guard-skills --skill docs-guard指定 agent 安装：
npx skills add amElnagdy/guard-skills --skill docs-guard --agent claude-code
npx skills add amElnagdy/guard-skills --skill docs-guard --agent codex安装后无需重启，在对话中说“审查一下这份 README 更新”或显式调用 $docs-guard 即可触发。
手动安装：把仓库 skills/docs-guard/ 目录（含 SKILL.md 及 references/ 下五份参考文档）复制进所用 agent 的技能目录。
更新：npx skills update docs-guard
11. 注意事项
- 只做核查与报告，不负责自动重写文档——发现问题后由用户或 agent 决定如何修复。
- 依赖代码库本身可读、可核实；若源码不可及（如私有依赖、外部服务），技能会明确标注“无法验证”而非静默放行。
- 不检查文档的行文风格（那是项目自身风格指南的职责），只负责核查技术性声明是否真实。
- 目前仅 Claude Code、Codex、OpenClaw、Hermes Agent 四个生态有安装层面的明确适配证据；实际使用体验因 agent 而异，建议安装后先在小范围文档上试跑一次。