Update Docs

What it does

When your agent uses it

• Asks to update documentation for my changes
• Check docs for this PR
• What docs need updating
• Sync docs with code

Example prompts

• “update documentation for my changes”
• “check docs for this PR”
• “what docs need updating”
• “/update-docs”

Workflow steps

12 steps, taken from the step headings in SKILL.md.

1. 1Get the diff
2. 2Identify documentation-relevant changes
3. 3Map to documentation files
4. 4Read the current documentation
5. 5Identify what needs updating
6. 6Apply updates with confirmation
7. 7Check for shared content
8. 8Validate changes
9. 9Determine the doc type
10. 10Create the file with proper naming
11. 11Use the appropriate template
12. 12Add related links

What it can do on your machine

Read from SKILL.md and the folder at commit a32ddfd. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • pnpm
  • git

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md. Its commands use pnpm and git, which can reach the network depending on how they are called.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Update Docs loads about 1.9k tokens when it runs, and up to ~5.3k if it reads all its reference files. Until then it costs about 134 tokens; SKILL.md has 468 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~134

When it runs · the whole SKILL.md, loaded when a task matches

~1.9k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~5.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from vercel/next.js at commit a32ddfd, republished under its MIT licence (© vercel). 468 words, ~1,894 tokens.

name

update-docs

description

This skill should be used when the user asks to "update documentation for my changes", "check docs for this PR", "what docs need updating", "sync docs with code", "scaffold docs for this feature", "document this feature", "review docs completeness", "add docs for this change", "what documentation is affected", "docs impact", or mentions "docs/", "docs/01-app", "docs/02-pages", "MDX", "documentation update", "API reference", ".mdx files". Provides guided workflow for updating Next.js documentation based on code changes.

metadata.internal

true

# See all changed files on this branch
git diff canary...HEAD --stat

# See changes in specific areas
git diff canary...HEAD -- packages/next/src/

# docs/02-pages/... file with shared content
---
source: app/building-your-application/optimizing/images
---

pnpm lint          # Check formatting
pnpm prettier-fix  # Auto-fix formatting issues

---
title: Feature Name
description: Brief description of what this feature does.
---

{/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}

Brief introduction to the feature.

## Reference

### Props

<div style={{ overflowX: 'auto', width: '100%' }}>

| Prop                    | Example            | Type   | Status   |
| ----------------------- | ------------------ | ------ | -------- |
| [`propName`](#propname) | `propName="value"` | String | Required |

</div>

#### `propName`

Description of the prop.

\`\`\`tsx filename="app/example.tsx" switcher
// TypeScript example
\`\`\`

\`\`\`jsx filename="app/example.js" switcher
// JavaScript example
\`\`\`

---
title: How to do X in Next.js
nav_title: X
description: Learn how to implement X in your Next.js application.
---

Introduction explaining why this guide is useful.

## Prerequisites

What the reader needs to know before starting.

## Step 1: First Step

Explanation and code example.

\`\`\`tsx filename="app/example.tsx" switcher
// Code example
\`\`\`

## Step 2: Second Step

Continue with more steps...

## Next Steps

Related topics to explore.

related:
  title: Next Steps
  description: Learn more about related features.
  links:
    - app/api-reference/functions/related-function
    - app/guides/related-guide

---
title: Page Title (2-3 words)
description: One or two sentences describing the page.
---

\`\`\`tsx filename="app/page.tsx" switcher
// TypeScript first
\`\`\`

\`\`\`jsx filename="app/page.js" switcher
// JavaScript second
\`\`\`

<AppOnly>Content only for App Router docs.</AppOnly>

<PagesOnly>Content only for Pages Router docs.</PagesOnly>

> **Good to know**: Single line note.

> **Good to know**:
>
> - Multi-line note point 1
> - Multi-line note point 2

© vercel, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (references) in .agents/skills/update-docs of vercel/next.js.

• SKILL.md
• references/CODE-TO-DOCS-MAPPING.md
• references/DOC-CONVENTIONS.md

Open the folder on GitHubat commit a32ddfd