Preface¶

Writing code with AI programming tools like Cursor, Claude Code, and Codex is fast—and so is writing accompanying documentation. Product descriptions, how-tos, API references, and troubleshooting pages can all be drafted directly by these models. The catch is that drafting is easy, but turning that draft into documentation that readers can actually use is not. Passive voice, marketing language (like easy, simple, or quick), titles named after features instead of user problems, code blocks missing language identifiers, and opening paragraphs that just repeat the previous section all make a page read like a draft manual, not a task-ready document.

The writing-guidelines maintained by Vercel Labs is an Agent Skill built to solve this exact problem. It does not write a full document from scratch. Instead, when you say “Help me review my docs / check my writing style”, it will audit your prose against the Vercel Writing Guidelines and return results with directly clickable file:line references. The guidelines themselves are stored in a remote repository and pulled fresh before each audit, so the rules stay up to date with the upstream source.

This article explains what it is, which checks it covers, how to install and enable it, and how to use it in your daily workflow.

What It Is¶

writing-guidelines is part of the official vercel-labs/agent-skills skill set, credited to Vercel, with a current metadata version of 1.0.0. It follows the standard Agent Skills (SKILL.md) format and can be installed into AI coding tools that support the standard, including Cursor, Claude Code, and Codex via the skills CLI. The skill directory currently only contains a single SKILL.md file, with no attached scripts/ or references/ folders.

One-sentence positioning: Perform compliance checks on specified documents and prose related to tone, structure, readability, and formatting, in accordance with the Vercel Writing Guidelines.

The official repository describes it as: Auditing documentation and prose against the Vercel Writing Handbook, covering over 80 rules spanning voice, structure, content types, code examples, formatting, and AI workflows. Trigger phrases include:
- Review my docs
- Check writing style
- Audit prose
- Review docs voice and tone
- Check this page against the writing handbook

The full guideline text is not hardcoded into the skill directory. Instead, it pulls the latest content from this URL before each audit:

https://raw.githubusercontent.com/vercel-labs/writing-guidelines/main/command.md

This command.md comes from the standalone repository vercel-labs/writing-guidelines. The repository’s README states that most rules are framework-agnostic, with a separate set of Vercel product-specific conventions at the end. The same repository also includes AGENTS.md, designed for writing documentation directly in compliance with the handbook during the drafting phase. The writing-guidelines skill takes a different approach: pull the rules first, then audit existing files.

Core Features and Audit Scope¶

The skill’s workflow is straightforward, as outlined in the official SKILL.md:
1. Pull the latest guidelines from the URL listed above
2. Read the user-specified file(s) or path pattern; prompt the user to confirm if no target is provided
3. Run a full audit against every rule in the guidelines
4. Output findings in the concise format required by the guidelines

Pulling the guidelines requires using WebFetch. The guidelines are grouped by topic, with major categories aligned to the repository README:
- Planning: Each page must have a content plan; declare Tutorial / How-to / Reference / Conceptual / Troubleshooting / Landing in meta.contentType; title pages using user-centric questions instead of feature names assigned by engineers
- Voice & tone: Use active voice, address readers directly with you, use imperative mood for steps; disable easy / simple / quick; remove filler words like very / just / really; avoid rhetorical questions
- Tone by content type: Tutorials should be instructional, How-tos should be concise, Reference pages should be citable, conceptual pages should be explainable, and troubleshooting pages should acknowledge the problem before providing fixes
- Headings & structure: Use sentence case for page titles; make section headings descriptive, do not use generic labels like Caveats; include a one-paragraph TL;DR at the start of each page, and a summary sentence at the start of each major section
- Lists / Code: Convert items with three or more entries into a list; all code blocks must include a language identifier; default to TypeScript for new examples; limit single code blocks to 80 columns and 25 lines
- Placeholders, units, & numbers: Use descriptive snake_case for placeholders (e.g. your_access_token_here); format units like 64 KB and 200 ms with a space between the value and unit
- Typography / Source formatting: Do not use em dashes as punctuation in body text; use curly quotes and the ellipsis character …; do not hard-wrap paragraphs in source code; do not separate sections with ---
- AI workflow / Review: Authors are responsible for final content, AI models should only propose drafts; disclose AI usage in PRs; draft a plan manually before asking an AI to write content

The guidelines also separately list a set of “AI generation telltale signs”, such as repeating the previous paragraph with phrases like “With this setup complete…”, splitting a single complete thought into three short sentences, using manual-style wording like provides / is configurable, and personifying machines (e.g. hand the browser a URL). These will all be flagged during audits.

Output requirements prioritize high signal-to-noise ratio: group results by file, use editor-clickable file:line references, point out the issue and its location, and avoid long explanatory text unless necessary. The example format from the official command.md is roughly as follows:

## 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

This format is ideal for a pre-PR sweep or a quick check after an AI has drafted a batch of pages, turning vague feedback like “this reads awkwardly” into actionable line-by-line changes.

Installation and Setup¶

This skill is released as part of vercel-labs/agent-skills. To install only this single skill, use the skills CLI (official documentation and equivalent commands are available on the skills.sh page):

npx skills add vercel-labs/agent-skills --skill writing-guidelines

You can also use the full GitHub repository URL:

npx skills add https://github.com/vercel-labs/agent-skills --skill writing-guidelines

Or directly reference the skill directory:

npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/writing-guidelines

If you want to install all skills in the repository at once:

npx skills add vercel-labs/agent-skills

Common options (refer to the skills CLI documentation for full details):
- -g / --global: Install to your user directory for cross-project access
- -y: Skip confirmation prompts, suitable for CI environments
- --list: Only list available skills in the repository without installing them

After installation, the agent will automatically select the skill when your task matches its description. The Vercel documentation states that the skills CLI works with multiple agents including Claude Code, GitHub Copilot, Cursor, and Cline. The exact installation directory varies by tool (common project-level paths include .cursor/skills/, .claude/skills/, and .agents/skills/), so refer to your tool’s documentation and CLI prompts for specifics.

If your agent supports custom command prompts, you can skip the skill entirely and use the command.md from the repository directly as an audit prompt. The skill essentially automates the process of pulling the latest version of this prompt and applying it to your specified files.

Typical Usage¶

Once installed, you do not need to memorize command names—trigger the skill using natural language. Official recommended phrases include:

Review my docs

Check writing style

Audit prose

Review docs voice and tone

Check this page against the writing handbook

A more reliable approach is to include a file or directory path upfront to avoid an extra round of follow-up questions from the agent:

Audit the How-to pages in content/docs using writing-guidelines, list issues with file:line references

Check docs/getting-started.mdx against the Vercel Writing Guidelines, focusing on tone, headings, and code blocks

Per the skill’s specification, the agent should first pull the latest command.md, then read your specified files, and finally output the audit results in compliance with the guidelines. If you do not provide a path, it will prompt you to specify which files to audit.

After the audit completes, treat the results as a checklist: prioritize high-impact changes first, such as fixing content types and titles, passive voice, banned words, and code blocks missing language identifiers, before moving on to formatting details like curly quotes and unit spacing. You can run the audit again on the same page after making changes to confirm it now shows ✓ pass.

Use Cases and Important Notes¶

This skill is well-suited for these scenarios:
- Conducting a unified tone and structure check on a batch of documents just drafted or heavily edited by AI
- Ensuring titles, summaries, and code examples align with your documentation site’s existing Tutorial / How-to / Reference content types
- Running an automated line-numbered audit before a manual code or docs review, so human reviewers can focus on technical accuracy
- Aligning a team’s review standards with Vercel’s public Writing Guidelines

Keep these notes in mind when using it:
1. Requires internet access to pull guidelines: Each audit needs access to the raw content from the writing-guidelines repository, and the agent must have network capabilities like WebFetch. If offline or with restricted network access, the rules may not load or may be out of date.
2. It is an audit tool, not an automatic full-content rewrite: The output focuses on identifying issues, and you will still need to tailor changes to your product’s terminology and target audience. If you want to write documentation in compliance with the handbook during the drafting phase, use the AGENTS.md from the same repository instead.
3. Some rules are specific to Vercel’s documentation site: For example, meta.contentType, the vercel/examples sample repository, ACME demo accounts, Dashboard deep link formats, and latest model strings in examples. Non-Vercel documentation projects can ignore these entries and focus on tone, structure, code blocks, and formatting instead.
4. English typography rules do not map perfectly to Chinese documentation: Curly quotes, em dashes, and ellipsis characters are primarily intended for English prose. Chinese pages can still be checked for structure, titles, code blocks, and banned marketing language, but do not apply all punctuation rules mechanically.
5. Refer to the official source: The skill’s behavior is defined by the SKILL.md in the repository and the remote command.md. If third-party translations or copies differ from the official version, defer to the original GitHub content.

Summary¶

The writing-guidelines skill turns Vercel’s writing handbook into an automatically triggerable agent audit workflow: pull the latest rules, then output high-signal file:line findings organized by file. For teams that regularly use AI to draft documentation and want to avoid inconsistent tone and structure, it is a low-cost, clearly standardized addition to their workflow.

Official links:
- Skill directory: https://github.com/vercel-labs/agent-skills/tree/main/skills/writing-guidelines
- Skill set repository: https://github.com/vercel-labs/agent-skills
- Skills.sh directory page: https://www.skills.sh/vercel-labs/agent-skills/writing-guidelines
- Guideline source file: https://raw.githubusercontent.com/vercel-labs/writing-guidelines/main/command.md
- Writing handbook repository: https://github.com/vercel-labs/writing-guidelines

Audit the documentation against Vercel writing guidelines using writing-guidelines