用途:防止文档腐化,通过系统审计、自动校验和流水线质量门禁维护文档质量。该技能为可继承技能,是 Documentarian 智能体的知识基础(技能是“做什么”,智能体是“谁来做”)。
主要能力:
- 计数消除:避免硬编码数量(如“109 个技能”)导致静默漂移,改为从文件系统派生,如统计 .github/skills/ 子目录、.github/agents/ 下 *.agent.md、.github/instructions/ 下 *.instructions.md、.github/prompts/ 下 *.prompt.md、.github/muscles/ 脚本文件。
- 文档头模式:操作类文档(回归清单、部署指南、QA 流程、发布工作流)应含完整元数据头,字段包括 Version、Date、Status、Testing Mode、Size/Scope、Key Changes、Purpose、Method、Expected Outcome。
- 5 轮质量流水线:依次执行品牌(语气、命名一致性)、架构(结构、计数、版本)、交叉引用(链接完整性、孤儿文件)、Lint(格式、Markdown 有效性)、合并(冗余与重叠)五轮,每轮单一焦点,不合并。
- 预检校验:发布或文档变更前运行自动检查,如所有 Markdown 链接可解析、无孤儿文件、必需章节存在、版本字符串与 package.json 一致。
- 链接完整性:内部链接每次提交校验,锚点链接每次提交校验,外部链接每周/每月批量 HTTP HEAD 检查,孤儿文件每发布检测,循环引用每季度图遍历。
- 陈旧度检测:为关键文档添加 Last Validated 日期,按新鲜(<30 天)、老化(30-90 天)、陈旧(90-180 天)、过期(>180 天)分级处理。
- 大型项目组织:文档超过 15 个文件时引入编号章节文件夹,每章 3-7 个文件,根 README.md 作目录。
- 多受众文档:为新手、有经验用户、贡献者、AI 智能体分别声明受众与格式偏好。
- 文档审计清单:7 项检查,含链接解析、无硬编码计数、版本字符串最新、代码示例可执行、文件引用存在、无孤儿文件、术语一致。
- CHANGELOG 最佳实践:每个用户可见变更一条、链接相关文档/issue、按 Added/Changed/Fixed/Removed 分组、版本头与 package.json 一致、ISO 日期、最新版本置顶。
使用方式:在文档套件上按顺序运行 5 轮流水线;发布前运行预检校验脚本(示例为 PowerShell 函数 Test-DocQuality);新增文件前先做交叉引用扫描,在同一提交中更新所有引用。
适用场景:文档审计、发布前校验、维护周期中的漂移检测、大型文档项目组织。
限制:资料未提供具体安装命令、收费、价格、平台支持或效果数据;示例脚本为 PowerShell,其他环境需自行适配。