用途
Doc Audit 是一个用于审计和维护代码库文档的 AI 技能，作者为 dgalarza，归属 agent-skills 集合。它把文档与实际的代码结构、配置和 Git 提交历史进行对照，检查文档的准确性、完整性与新鲜度。资料将其定位为 agent-ready 的维护配套技能：agent-ready 负责搭建文档骨架，doc-audit 负责让文档保持准确。
主要能力
该技能围绕四个维度开展评估：
- 完整性：预期的文档产物是否存在，入口文档（AGENTS.md/CLAUDE.md）是否有实质内容，是否有带代码地图的 ARCHITECTURE.md，docs/ 和 ADR 是否存在；对 monorepo 还要检查每个包是否都有文档。
- 准确性：ARCHITECTURE.md 代码地图中的文件路径是否真实存在，文档中的端口号是否与 docker-compose.yml 和 .env 一致，构建/测试/运行命令是否与 package.json/Makefile 中的脚本相符，依赖与技术引用是否与实际一致；对 AI 项目还要核对智能体/工具表与实际定义。
- 新鲜度：文档与代码的最后修改时间对比，是否存在新增功能但未更新文档的提交，最后一个 ADR 相对于最近重大变更的时间，文档中是否有 TODO/FIXME 标记。
- 一致性：文档之间是否有失效的 Markdown 链接，内容是否在多个文件中重复，不同文档是否给出相互冲突的指令，CLAUDE.md 是否为指向 AGENTS.md 的符号链接。
审计前会先做侦察：检测项目类型（package.json、Gemfile、requirements.txt、pyproject.toml、go.mod、Cargo.toml、build.sbt、pom.xml、*.csproj 等），查找各级文档文件、docs/ 目录内容、ADR 文件、顶层结构、源码文件、入口点、配置文件以及最近 7 天的 Git 变更；若存在 turbo.json、nx.json、lerna.json、pnpm-workspace.yaml 或带 workspaces 的 package.json，则按 monorepo 模式处理，否则按单包模式处理。
使用方式
该技能按用户意图选择运行模式：
| 用户意图 | 模式 | 触发说法示例 |
|---|---|---|
| 检查文档健康 | audit | "audit docs"、"check documentation"、"are docs up to date" |
| 修复问题 | fix | "fix docs"、"update documentation"、"sync docs" |
| 完整分析 + 路线图 | full | "full doc audit"、"doc audit with roadmap" |
意图不明确时默认进入 audit 模式（只读、安全）。
- audit（默认，只读）：不修改任何文件，输出审计报告。发现按严重程度分类：Critical（文档主动误导，如错误路径、错误命令、矛盾指令）、Warning（过时或不完整，如缺少产物、计数过时、链接失效）、Info（轻微问题，如描述轻微漂移、少量重复、可选文档缺失）。报告中尽量给出具体文件路径与行号及证据。
- fix（会修改文件）：先执行完整审计，再自动修复无需人工判断的安全机械性问题，包括：更新代码地图中已移动的文件路径、补充新包/新源码目录、移除已删除文件的引用、按 docker-compose.yml 或 .env 修正端口号、按代码修正环境变量名、把磁盘上存在但未列出的新 ADR 加入 docs/README.md 索引、修复因文件移动（而非删除）导致的相对链接、更新表格中的计数（智能体数、工具数、包数）。每处修改会说明改什么、为什么，并展示修改前后；随后把文档改动提交，提交信息形如
doc-audit: [修复摘要]。之后报告仍需人工判断的问题，如需要重写的结构性变更、仅凭代码无法确定正确内容的过时段落、需要领域知识的新功能文档、可能已不再遵循的约定、以及应拆分/合并/重组的章节。 - full（修复 + 路线图）：在 fix 流程之后生成按优先级排序的改进计划：优先级 1 为准确性修复（需重写的误导性章节），优先级 2 为覆盖缺口（新的嵌套 AGENTS.md、新指南、DOMAIN.md，以及为已做但未记录的决定补写 ADR），优先级 3 为结构改进（拆分大文档、补充常见工作流指南、调整 docs/ 布局），优先级 4 为流程改进（文档新鲜度 CI 检查、文档更新触发条件、定期审计节奏）。路线图以编号的可执行清单呈现。
适用场景
适用于维护 AGENTS.md、CLAUDE.md、ARCHITECTURE.md、README.md、CONTRIBUTING.md、docs/ 目录与 ADR 等文档的代码库，尤其是希望文档对 AI 代理保持准确可读的项目，以及使用 monorepo 结构、需要逐包核查文档的工程。
限制
资料未说明该技能的收费、价格、支持的代理平台范围、依赖前提及实际使用效果，这些信息暂未提供。资料中的 shell 片段属于技能内部实现细节，未经说明不具备独立运行保证。