前言¶
用 Cursor、Claude Code、Codex 这类 AI 编程工具写代码很快，连带写文档也很快。产品说明、How-to、API 参考、排障页，模型都能直接起草。问题是：起草容易，写成「能给读者用」的文档并不容易。被动语态、营销词（easy / simple / quick）、标题按功能命名而不是按用户问题命名、代码块缺语言标记、段落开头先复述上一段，这些都会让页面读起来像说明书草稿，而不是能完成任务的文档。
Vercel Labs 维护的 writing-guidelines 正是为这个问题准备的 Agent Skill。它不负责从零写一篇文档，而是在你说「帮我 review docs / 检查一下写作风格」时，按 Vercel Writing Guidelines 去审 prose，并给出可直接跳转的 file:line 结果。规范本身放在远程仓库，每次审查前都会重新拉取，规则跟着上游更新。
本文说明它是什么、覆盖哪些检查项、怎么安装启用，以及日常怎么用。
这是什么¶
writing-guidelines 属于 vercel-labs/agent-skills 官方技能集，作者标注为 vercel，当前元数据版本为 1.0.0。它遵循通用的 Agent Skills（SKILL.md）格式，可用 skills CLI 安装到 Cursor、Claude Code、Codex 等支持该标准的 AI 编程工具中。Skill 目录里目前只有一份 SKILL.md，没有附带 scripts/ 或 references/。
一句话定位：按 Vercel Writing Guidelines，对指定文档与 prose 做语气、结构、可读性与排版相关的合规审查。
官方仓库对它的描述是：对照 Vercel 写作手册审查文档和 prose，覆盖 80+ 条规则，范围包括 voice、结构、内容类型、代码示例、排版和 AI 工作流。触发场景包括：
- Review my docs
- Check writing style
- Audit prose
- Review docs voice and tone
- Check this page against the writing handbook
规范正文不在 Skill 目录里写死，而是每次审查前从下面地址拉取最新内容：
https://raw.githubusercontent.com/vercel-labs/writing-guidelines/main/command.md
这份 command.md 来自独立仓库 vercel-labs/writing-guidelines。该仓库 README 写明：大部分规则与具体框架无关，文末另有一组 Vercel 产品相关约定。同一仓库还提供 AGENTS.md，给「生成文档时就按手册写」用；writing-guidelines 这个 Skill 走的是另一条路：先拉规则，再审已有文件。
核心功能与检查范围¶
Skill 的工作流程很直接，官方 SKILL.md 写明了四步：
- 从上述 URL 拉取最新指南
- 读取用户指定的文件（或路径模式）；未指定则先向用户确认
- 按指南中的全部规则逐项检查
- 按指南要求的简洁格式输出发现项
拉取时要求使用 WebFetch。指南按主题分组，和仓库 README 对齐的主要类别包括：
- Planning：每页要有内容计划；在
meta.contentType中声明Tutorial/How-to/Reference/Conceptual/Troubleshooting/Landing；标题按用户问题来写，而不是按工程师给功能起的名字 - Voice & tone：主动语态、直接用
you、步骤用祈使句；禁用easy/simple/quick；去掉very/just/really这类填充词；不用修辞问句 - Tone by content type：教程偏引导、How-to 要短、Reference 要可引用、概念页要能转述、排障页先承认问题再给修法
- Headings & structure：页面标题用 sentence case；小节标题要能看出内容，不要只写
Caveats；每页开头一段 TL;DR，每个大节开头一句摘要 - Lists / Code：三项及以上改成列表；代码块必须带语言标记；新示例默认 TypeScript；单段代码建议不超过 80 列、25 行
- Placeholders, units, & numbers：占位符用描述性
snake_case（如your_access_token_here）；容量写成64 KB、200 ms - Typography / Source formatting：正文不用破折号当标点；用弯引号和省略号字符
…；源码里段落不硬折行；章节之间不用---分隔 - AI workflow / Review：作者对内容负责，模型只提案；PR 里披露 AI 使用；先手写计划再让模型写
指南还单独列出一批「AI 生成痕迹」，例如用「With this setup complete…」复述上一段、把一个完整意思拆成三句短句、说明书式用词（provides / is configurable）、以及把机器拟人化（hand the browser a URL）。审查时这些都会被标出来。
输出要求高信噪比：按文件分组，使用编辑器可点击的 file:line，点出问题与位置，非必要不展开长篇解释。官方 command.md 里的示例形态大致如下：
## content/docs/sandbox.mdx
content/docs/sandbox.mdx:1 - missing meta.contentType
content/docs/sandbox.mdx:12 - title "Vercel Sandbox" is feature-shaped, not user-question
content/docs/sandbox.mdx:24 - passive voice ("the sandbox is created...")
content/docs/sandbox.mdx:31 - banned word "easy"
content/docs/sandbox.mdx:47 - "..." → "…"
content/docs/sandbox.mdx:58 - code block missing language tag
## content/docs/cron.mdx
✓ pass
这种形态适合在文档 PR 前、或 AI 批量起草页面之后做一轮「扫雷」，把模糊的「读着别扭」落成可改的行号。
安装与启用¶
该 Skill 随 vercel-labs/agent-skills 发布。只装这一项时，可用 skills CLI（官方文档与 skills.sh 页面均提供同类命令）：
npx skills add vercel-labs/agent-skills --skill writing-guidelines
也可以用完整 GitHub 地址：
npx skills add https://github.com/vercel-labs/agent-skills --skill writing-guidelines
或直接指向 Skill 目录：
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/writing-guidelines
若希望一次装入该仓库下全部技能：
npx skills add vercel-labs/agent-skills
常用选项（以 skills CLI 文档为准）：
-g/--global：装到用户目录，跨项目可用-y：跳过确认，适合 CI--list：只列出仓库里有哪些 Skill，不安装
安装完成后，Agent 会在任务与 Skill 描述匹配时自动选用。Vercel 文档说明 skills CLI 可对接包括 Claude Code、GitHub Copilot、Cursor、Cline 等在内的多种 Agent；具体落盘目录因工具而异（例如项目级常见 .cursor/skills/、.claude/skills/、.agents/skills/ 等），以当前工具文档与 CLI 提示为准。
如果所用 Agent 支持 command prompt，也可以不经过这个 Skill，直接使用仓库里的 command.md 作为审查提示。Skill 做的事情，本质上就是每次审查前把这份提示拉新，再套到你指定的文件上。
典型用法¶
装好后，不必背命令名，直接用自然语言触发即可。官方推荐的说法包括：
Review my docs
Check writing style
Audit prose
Review docs voice and tone
Check this page against the writing handbook
更稳妥的做法是带上文件或目录，减少 Agent 再追问的一轮：
用 writing-guidelines 审查 content/docs 下的 How-to 页面，按 file:line 列出问题
对照 Vercel Writing Guidelines 检查 docs/getting-started.mdx，重点看语气、标题和代码块
按 Skill 约定，Agent 应先拉取最新 command.md，再读你指定的文件，最后按规范输出。若你没给路径，它会先问要审哪些文件。
审查结束后，建议把结果当 checklist：优先改内容类型与标题、被动语态、禁用词、缺语言标记的代码块这类高影响项，再处理弯引号、单位空格等排版细则。同一页面改完后可以再跑一轮，确认是否变成 ✓ pass。
适用场景与注意事项¶
比较适合这些场景：
- AI 刚起草或大改过一批文档，需要按统一口径扫一遍语气和结构
- 文档站点已经按 Tutorial / How-to / Reference 分型，希望标题、摘要、代码示例跟手册对齐
- Code Review 或 Docs Review 前先让 Agent 按清单标行号，人再盯技术对错
- 希望团队审查口径对齐 Vercel 公开的 Writing Guidelines
使用时注意几点：
- 依赖联网拉取规范。每次审查要能访问
writing-guidelines的 raw 内容，并且 Agent 需要 WebFetch 这类联网能力；离线或网络受限时，规则可能拿不到或不是最新版。 - 它是审查流程，不是自动改完全文的写作器。输出偏「指出问题」，具体怎么改仍要结合产品术语和读者对象。若希望生成阶段就按手册写，应另外使用该仓库提供的
AGENTS.md。 - 规则里有一部分是 Vercel 文档站约定。例如
meta.contentType、vercel/examples示例仓库、ACME 演示账号、Dashboard 深链格式、示例里的最新模型字符串。非 Vercel 文档项目可以忽略这些条目，把注意力放在语气、结构、代码块和排版上。 - 英文排版细则对中文文档不完全一一对应。弯引号、破折号、省略号字符等规则主要针对英文 prose；中文页面仍可检查结构、标题、代码块和禁用营销词，但不必机械套用全部标点规则。
- 以一手资料为准。Skill 行为以仓库中的
SKILL.md与远程command.md为准；第三方转载若与官方不一致，以 GitHub 原文为准。
小结¶
writing-guidelines 把 Vercel 的写作手册变成可自动触发的 Agent 审查流程：先拉最新规则，再按文件输出高信噪比的 file:line 发现。对经常用 AI 起草文档、又担心语气和结构被带偏的团队，它是一个成本低、口径清晰的补充环节。
官方地址：
- Skill 目录：https://github.com/vercel-labs/agent-skills/tree/main/skills/writing-guidelines
- 技能集仓库：https://github.com/vercel-labs/agent-skills
- 目录页：https://www.skills.sh/vercel-labs/agent-skills/writing-guidelines
- 规范源：https://raw.githubusercontent.com/vercel-labs/writing-guidelines/main/command.md
- 写作手册仓库：https://github.com/vercel-labs/writing-guidelines
