代码和文档不同步，大概是开源项目里最普遍的慢性病。API 改了签名，文档还停在三个月前；组件加了新 prop，示例代码还是旧的。小项目可以靠维护者记性好，但 Next.js 这种几千个文件的仓库，靠记性早就崩了。
Vercel 的做法是把这个流程塞进 Agent 里。next.js 仓库的 .agents/skills 目录下维护着一个官方 skill，叫 update-docs。维护者审查 PR 时，让 AI 顺着代码变更找出受影响的文档，逐个确认修改，甚至从零搭建新功能的文档骨架。
这个 skill 跟市面上大多数文档生成类工具不是一个路子。它不追求”一句话生成一篇文档”，而是把”文档审查”这个动作拆成可执行的步骤，每一步都要求人工确认。第一次看到它的工作流时我有点意外，一个官方 skill 居然主动放弃全自动。
这篇拆解它的三条工作流、两个 reference 文件，再聊聊一个反直觉的设计选择：Vercel 为什么要让这个 skill 保留人工环节。如果你在维护自己的开源项目，或者在做 Agent 技能开发，这套设计值得抄的地方不少。
使用场景
先看它解决什么问题。Next.js 每天都有大量 PR 合入 canary 分支，其中相当一部分改了公共 API。维护者审查每个 PR 时都得回答一个问题：这次改动影响哪些文档？以前这是纯人肉活，diff 代码、翻 docs 目录、对照 API 参考，一趟下来小半天。
skill 的触发条件写得非常直白。description 里列了一长串触发词，覆盖了各种文档维护意图：
-
“update documentation for my changes” -
“check docs for this PR” -
“what docs need updating” -
“sync docs with code” -
“scaffold docs for this feature” -
“review docs completeness”
除了这些句子，路径和格式关键词也能触发它：
-
“docs/” 目录路径 -
“MDX” 文件格式 -
“API reference” 常用短语
这种”句子加路径词”双通道的触发设计，让它在自然对话和文件操作场景里都能被命中。
安装方式很常规，一条命令的事。它发布在 Smithery 上，作者是 Vercel 官方，归类在 Writing 分类下，源码就放在 next.js 仓库里：
npx skills add https://smithery.ai/skills/vercel/update-docs
整体结构见下图。skill 的核心是三条平行的工作流：分析代码变更、更新已有文档、搭建新功能文档，外加两个 reference 文件做支撑，最后统一用 lint 收尾。
注意它跟普通文档生成器的定位差异。普通工具的目标是”写出一篇好读的文档”，update-docs 的目标是”文档与代码保持同步”。这两个目标导向的工作流完全不同，前者重生成，后者重比对和确认。这个定位差异贯穿了它的所有设计。
还有个容易被忽略的点：这个 skill 是 Vercel 自己在日常工作流里真实使用的，不是摆出来做样子的。next.js 仓库的每个 PR 审查都可能触发它，它经受的是真实开源项目的检验。市面上很多文档工具是 demo 级的，跑通一个示例就完事，而 update-docs 需要处理真实 PR 里千奇百怪的改动，这个差距是设计出来的。
操作流程
三条工作流可以按需触发。审查一个 PR 时通常按”分析、更新、搭建”的顺序走，但也可以单独调用其中一条。下面拆开看。
分析代码变更的第一步是拿 diff。skill 默认你从 canary 分支切出来，所以命令是 git diff canary…HEAD –stat，先看整体改了哪些文件，再针对特定目录深入：
# 看整个分支改了什么
git diff canary...HEAD --stat
# 聚焦某个区域
git diff canary...HEAD -- packages/next/src/
拿到 diff 之后不是所有改动都要写文档。skill 给了一套粗粒度的映射思路：client/components 下的改动通常影响组件 API 参考，src/server 影响函数 API 参考，build 目录影响配置文档。先按这个筛一遍，再落到具体文件。
真正把”某个源码文件对应哪篇文档”讲清楚的，是 references/CODE-TO-DOCS-MAPPING.md。比如 image.tsx 对应 docs/01-app/03-api-reference/02-components/image.mdx，config-shared.ts 对应 next-config-js 配置文档。这张表让 Agent 不用在几千个文件里猜，直接定位：
除了映射表，references 下还有一份 DOC-CONVENTIONS.md，是文档的风格规范和规则手册。MDX 怎么写、示例代码块用什么格式、标题怎么分层，都写在这份文件里。两份 reference 的分工很清晰：映射表解决”改哪个文件”，规范文件解决”改成什么样”。对 Agent 来说，这比在 prompt 里堆规则可靠得多，因为文件可以随时更新，不需要重新生成 skill。
更新已有文档的流程最有意思。skill 要求先读现有文档，理解结构和 frontmatter 字段，再列出需要改的点。常见的更新类型被归成四类：
-
新增 props 或选项：补进 props 表格，并新写一段说明用法 -
行为变化：更新描述文字和示例代码 -
废弃功能：加废弃提示和迁移指引 -
新示例：按文档既有约定补代码块
列完清单后逐个修改，每个变更都要先展示给用户、等确认、再落笔。这一步是整套流程里最像”工程”的地方，它把 AI 的角色牢牢钉在”助手”而不是”执行者”上。
Next.js 文档有个特殊结构：App Router 和 Pages Router 两套文档部分内容共享，通过 frontmatter 的 source 字段引用。skill 特意写明：遇到这种文件，要改的是 source 指向的源文件，不是引用它的那份。这个细节不写清楚，Agent 大概率改错文件。
第三条工作流负责从零搭建新功能的文档，这块最容易踩坑，因为新文档没有参照物。skill 的做法是先按功能类型定目录和模板：新组件进 API reference 的 components 目录，新函数进 functions 目录，新配置项进 config 目录，概念类指南进 guides。类型决定位置，位置决定模板。
文件命名也有硬约定，kebab-case 加数字前缀，保证目录排序稳定：
-
组件文档：docs/01-app/03-api-reference/02-components/ -
函数文档：docs/01-app/03-api-reference/04-functions/ -
配置文档：docs/01-app/03-api-reference/05-config/ -
概念指南：docs/01-app/02-guides/
模板自带标准骨架。API reference 模板包含 title、description 的 frontmatter 和 Props 表格结构，guide 模板包含 Prerequisites 和分步骤说明。写完还要在 frontmatter 里补 related 链接，把新文档接进整个知识网络，不然它就是个孤岛。
所有修改完成后用 pnpm lint 检查格式，pnpm prettier-fix 自动修。文档是代码库的一部分，格式不过关过不了 CI。整个更新流程见下图：
洞察与反思
第一个值得抄的设计：把”代码到文档的映射”写成显式的 reference 文件，而不是让 Agent 自己摸索。这个思路的本质是给 Agent 建索引。大模型的优势在理解和生成，但定位类任务靠记忆不靠谱，一张准确的映射表胜过十段 prompt 提示。
第二个设计取舍更反直觉：文档修改强制人工确认。原因不难猜，文档是面向用户的公共资产，改错一个 prop 说明，影响的是整个生态的开发者。Vercel 宁可让流程慢一点，也不让 Agent 放开手脚直接改。这个克制放在今天一堆追求全自动的 skill 里，反而显得稀缺。
有个细节挺有意思。2026 年 3 月 Vercel 给仓库里 12 个 .agents/skills 全部加上了 metadata.internal: true，外部执行 npx skills add 时这些框架开发技能不再出现在列表里，只保留 next-compile。但 update-docs 本身通过 Smithery 分发，依然可以直接安装。这说明它既是内部工作流，也刻意对外输出。
它的局限也很明显：深度绑定 Next.js。docs/01-app、docs/02-pages 的目录结构，MDX 文件格式，source 字段共享模式，canary 分支假设，全是这个仓库特有的。换到别的项目，映射表和模板基本要重写。它本质上是”为 Next.js 定制的文档审查流水线”，不是通用文档工具。
但模式可以平移。任何维护大型项目的团队，都能照着这个结构做一个自己的文档 skill：把代码到文档的映射写进 reference 文件，把审查流程固化成确认式工作流，用 lint 做最后的把关。这比让 AI 自由发挥可靠得多。
资源地址
| 资源 | 链接 |
|---|---|
| Smithery 页面 | https://smithery.ai/skills/vercel/update-docs |
| GitHub 源码 | https://github.com/vercel/next.js/tree/canary/.agents/skills/update-docs |
| SkillSafe 快照 | https://skillsafe.ai/skill/@vercel/update-docs |
总结
update-docs 的价值不在”AI 自动写文档”，而在把文档审查这个高频低效的流程工程化。拆开看，每个环节都在回答同一个问题：怎么让 Agent 可靠地维护公共文档。
-
显式映射：用 reference 文件替代 Agent 的猜测 -
逐条确认：公共产物的每次修改都留人工确认点 -
模板脚手架：新文档按模板生成，保证结构一致 -
lint 收尾：格式问题交给工具兜底
这四个环节单独拿出来都不稀奇，组合在一起就是一个可靠的文档审查流水线。
对做 Agent 技能开发的人，最有启发的是两条：
一是用 reference 文件给 Agent 建外部知识库，把”猜”变成”查”；
二是划清自动与确认的边界，生成类步骤可以放手，涉及公共产物的修改必须留人工环节。
如果你在维护自己的开源项目，照着这个结构做一个文档同步 skill，成本不高。映射表写清楚，工作流拆到位，剩下的交给 Agent。文档与代码同步这件事，不该靠记性。