前言¶
用 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
