在Agent应用逐渐渗透到软件工程各个环节的这两年，写文档这件事悄悄发生了变化。以前程序员写完代码，还要挤出时间补README、补API文档、补贡献指南，现在这些活儿越来越多地交给了Agent里的技能模块去完成。这类技能在Anthropic的体系里被称为Agent Skills，本质上是一个个装着说明书、脚本和资源文件的文件夹，Claude在需要时动态加载，用完就放下，不占常驻的上下文空间。
这次搜集整理了Anthropic官方仓库、Claude Code文档、以及一线技术团队的实战案例后，梳理出了十个在agent应用里写软件文档时最常被调用的技能。下面按照它们在文档生命周期里出现的顺序，逐一展开说说。
🗂️ 技能全景图
先用一张图把这十种技能在文档工作流里的位置理清楚，看完图再往下读会更顺。
📋 十大核心技能一览
下面这张表把每个技能的作用、典型输入输出、以及在Agent Skills规范里对应的自由度等级都列出来，方便快速对照。
| 技能名称 | 主要作用 | 典型触发场景 |
|---|---|---|
| README生成与维护 | 从项目结构、依赖文件反推项目说明 | 新项目初始化、依赖变更后同步 |
| API文档自动提取 | 解析路由处理函数、函数签名生成接口文档 | 后端接口新增或修改 |
| Docstring规范化 | 检查并补全函数、类的文档字符串 | 代码审查、CI流水线 |
| CONTRIBUTING指南生成 | 生成贡献流程、代码规范说明 | 开源项目开放协作前 |
| 变更日志生成 | 从git提交记录归纳版本变更 | 发版前 |
| 文档陈旧检测与审计 | 扫描CLAUDE.md、AGENTS.md等文件里失效的路径引用 | 定期巡检、重构后 |
| 术语与风格一致性检查 | 统一命名、语气、格式规范 | 多人协作文档合并 |
| 图表与架构可视化 | 生成Mermaid、序列图辅助理解系统结构 | 架构说明、新人上手文档 |
| 多格式文档转换 | 在Markdown、PDF、DOCX、PPTX之间转换 | 对外交付、汇报材料 |
| 测试驱动的文档验证 | 运行/验证应用行为，确保文档描述与实际一致 | 发布前最终校验 |
🔍 逐项拆解
README生成与维护技能
这是最基础也是最高频的一类，Agent会读取package.json、Makefile或项目里的现有README，推断出项目类型、启动方式、依赖关系，然后生成或更新说明文档。Claude Code里的/run和/verify两个内置技能就依赖README里的信息去推断如何启动项目，某种程度上说明README不只是给人看的，也是给Agent自己看的"地图"。
API文档自动提取技能
这个技能特别适合有明确路由结构的项目，比如FastAPI、Express这类框架。Dosu团队做过一个很生动的案例，他们给一个叫Overdue的FastAPI项目跑了/doc-it技能，直接从六个API模块的路由处理函数里抓取错误字符串和参数说明，生成了完整的接口文档，省掉了人工翻源码的时间。
Docstring规范化技能
代码里散落的注释往往质量参差不齐，这个技能负责给函数、类补全标准格式的文档字符串。它属于中等自由度的技能类型，Anthropic官方指南里管这类叫"伪代码或带参数的脚本"模式，既给出模板又留出灵活调整的空间。
CONTRIBUTING指南生成技能
开源项目开放外部协作前，通常需要一份说明代码规范、提交流程、分支策略的指南。这类内容变化不大但格式要求严格，属于低自由度任务，Agent按照固定模板填充项目特有信息即可。
变更日志生成技能
从git commit历史里提炼出面向用户的变更说明，这一步最考验Agent对提交信息语义的理解能力。做得好的技能会自动区分新增功能 、修复问题 、破坏性变更三类，而不是简单地把commit信息堆在一起。
文档陈旧检测与审计技能
这可能是最容易被忽视却最有价值的一类。Agent工具普及后，项目里除了给人看的文档，还多了一层专门给Agent看的文档，比如CLAUDE.md和AGENTS.md，用来告诉Agent文档在哪里、哪些命令能跑、什么样的输出算合格。这类文件一旦过期，Agent不会主动报错，只会默默信任一个失效的路径，或者自己摸索出偏门的解决方式，代价是浪费时间和token。定期跑一次审计技能，扫出这些"僵尸引用"，能省下不少排查成本。
术语与风格一致性检查技能
多人协作或跨模块拼接文档时，命名习惯、语气风格很容易打架。这个技能负责统一术语表、检查大小写规范、纠正前后矛盾的表述，属于典型的高自由度任务，因为没有唯一正确的风格，只有符合团队约定的风格。
图表与架构可视化技能
复杂系统光靠文字描述效率太低，这时候Mermaid流程图、序列图就派上用场了。Agent会根据代码依赖关系或模块调用链自动生成图表代码，新人看图比读三千字说明理解得更快。
多格式文档转换技能
Anthropic在其官方skills仓库里公开了docx、pdf、pptx、xlsx这几个文档处理技能的源码，专门用来支撑Claude在不同格式之间转换文档能力，这些技能虽然不是完全开源，但作为参考案例展示了复杂技能该如何组织。对需要把Markdown文档导出成汇报PPT或者合同PDF的团队来说，这类技能价值很大。
测试驱动的文档验证技能
文档写得再漂亮，如果和实际代码行为不符也是白搭。Claude Code里的/verify技能会实际构建并运行应用，用真实运行结果去校验文档里描述的功能是否属实，而不是仅仅跑一遍单元测试就了事。这一步往往被放在发布流程的最后一环。
💡 写好这些技能的三条底层原则
翻了Anthropic官方的技能编写指南，发现真正决定这些技能好不好用的，不是技能本身列了多少条规则，而是三个更底层的判断标准。
- 克制表达，Claude本身已经很聪明，技能文件里不需要重复解释常识性内容，每一段文字都要问自己一句这段话值不值这个token成本
- 匹配自由度，操作越脆弱越容易出错的环节（比如数据库迁移），就要给出低自由度的精确指令；决策依赖上下文的环节（比如代码审查），则应该给高自由度的方向性建议
- 跨模型测试，同一个技能在Haiku上可能引导不够，在Opus上又可能显得啰嗦，编写时要考虑实际会跑在哪些模型上
这三条原则说白了就是把"该说的话说清楚，不该说的话别啰嗦"落到了工程实践里，这也是为什么Agent写文档能越来越靠得住。
参考资料
anthropics/skills README, GitHub, github.com/anthropics/...
A Claude Code Skill for Auto-Generating Project Docs, Dosu, dosu.dev/blog/claude...
Extend Claude with skills, Claude Code Docs, code.claude.com/docs/en/ski...
Skill authoring best practices, Claude Platform Docs, platform.claude.com/docs/en/age...