Index of every page on this site: llms.txt
All skills
vercel avatar

/update-docs

@495cbfa official
by vercelvercel/next.js144k stars
32,812
Run it yourself

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.

  • 3 files
  • 20.6 KB
  • Updated 6 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/vercel/next.js/update-docs

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈134 tokens for metadata: the name and description. ≈1.7k when used: this file. ≈3.4k more on demand in 2 files.

Description uses 6.7% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈538 characters, or 6.7%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Next.js Documentation Updater

Guides you through updating Next.js documentation based on code changes on the active branch. Designed for maintainers reviewing PRs for documentation completeness.

Quick Start

  1. Analyze changes: Run git diff canary...HEAD --stat to see what files changed
  2. Identify affected docs: Map changed source files to documentation paths
  3. Review each doc: Walk through updates with user confirmation
  4. Validate: Run pnpm lint to check formatting
  5. Commit: Stage documentation changes

Workflow: Analyze Code Changes

Step 1: Get the diff

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

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

Step 2: Identify documentation-relevant changes

Look for changes in these areas:

Source Path Likely Doc Impact
packages/next/src/client/components/ Component API reference
packages/next/src/server/ Function API reference
packages/next/src/shared/lib/ Varies by export
packages/next/src/build/ Configuration or build docs
packages/next/src/lib/ Various features

Step 3: Map to documentation files

Use the code-to-docs mapping in references/CODE-TO-DOCS-MAPPING.md to find corresponding documentation files.

Example mappings:

  • src/client/components/image.tsx → docs/01-app/03-api-reference/02-components/image.mdx
  • src/server/config-shared.ts → docs/01-app/03-api-reference/05-config/

Workflow: Update Existing Documentation

Step 1: Read the current documentation

Before making changes, read the existing doc to understand:

  • Current structure and sections
  • Frontmatter fields in use
  • Whether it uses <AppOnly> / <PagesOnly> for router-specific content

Step 2: Identify what needs updating

Common updates include:

  • New props/options: Add to the props table and create a section explaining usage
  • Changed behavior: Update descriptions and examples
  • Deprecated features: Add deprecation notices and migration guidance
  • New examples: Add code blocks following conventions

Step 3: Apply updates with confirmation

For each change:

  1. Show the user what you plan to change
  2. Wait for confirmation before editing
  3. Apply the edit
  4. Move to the next change

Step 4: Check for shared content

If the doc uses the source field pattern (common for Pages Router docs), the source file is the one to edit. Example:

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

Edit the App Router source, not the Pages Router file.

Step 5: Validate changes

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

Workflow: Scaffold New Feature Documentation

Use this when adding documentation for entirely new features.

Step 1: Determine the doc type

Feature Type Doc Location Template
New component docs/01-app/03-api-reference/02-components/ API Reference
New function docs/01-app/03-api-reference/04-functions/ API Reference
New config option docs/01-app/03-api-reference/05-config/ Config Reference
New concept/guide docs/01-app/02-guides/ Guide
New file convention docs/01-app/03-api-reference/03-file-conventions/ File Convention

Step 2: Create the file with proper naming

  • Use kebab-case: my-new-feature.mdx
  • Add numeric prefix if ordering matters: 05-my-new-feature.mdx
  • Place in the correct directory based on feature type

Step 3: Use the appropriate template

API Reference Template:

---
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
\`\`\`

Guide Template:

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

Step 4: Add related links

Update frontmatter with related documentation:

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

Documentation Conventions

See references/DOC-CONVENTIONS.md for complete formatting rules.

Quick Reference

Frontmatter (required):

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

Code blocks:

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

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

Router-specific content:

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

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

Notes:

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

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

Validation Checklist

Before committing documentation changes:

  • Frontmatter has title and description
  • Code blocks have filename attribute
  • TypeScript examples use switcher with JS variant
  • Props tables are properly formatted
  • Related links point to valid paths
  • pnpm lint passes
  • Changes render correctly (if preview available)

References

  • references/DOC-CONVENTIONS.md - Complete frontmatter and formatting rules
  • references/CODE-TO-DOCS-MAPPING.md - Source code to documentation mapping

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 495cbfa. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 6 months ago
metadata
{
  "internal": true
}

README badge

README badge for vercel/next.js/update-docs

Guides you through analyzing code changes on a branch and updating corresponding Next.js documentation files with confirmation prompts at each step. Includes workflows for modifying existing docs, scaffolding new feature documentation, and validating changes against formatting rules.

Generated from the current SKILL.md.

When should I use this skill?
Use this skill when reviewing a PR for documentation completeness, updating docs after code changes, or scaffolding documentation for new features in Next.js. It guides you through mapping code changes to documentation files and applying updates with confirmation.
Does this work with both App Router and Pages Router documentation?
Yes. The skill handles both routers and teaches you to use `<AppOnly>` and `<PagesOnly>` components for router-specific content. It also handles Pages Router docs that source from App Router files via the `source` field pattern.
What does this skill actually do?
It provides a guided workflow to analyze code diffs, identify which documentation files are affected, review and update those files, scaffold new feature docs from templates, and validate changes using Next.js linting rules.
Can this skill update documentation automatically?
No. The skill guides you through the process and waits for your confirmation before applying each edit. It teaches conventions and templates but requires human decision-making on what content changes are needed.

Generated from the current SKILL.md. These answers refresh after source changes.