# Write Api Reference

> Produce documentación de referencia de API de Next.js — funciones, componentes, convenciones de archivo, directivas y opciones de configuración — como página .mdx con frontmatter, ejemplos y reglas.

Fuente: https://skillsagentes.com/skills/vercel/next.js/write-api-reference
Markdown: https://skillsagentes.com/skills/vercel/next.js/write-api-reference.md

Repositorio: https://github.com/vercel/next.js
Autor: vercel
Licencia: MIT
Actualizado: hace 3 meses
Coste de contexto: 149 tok instalada, 2.2k tok al activarse, 2.2k tok con todos los archivos del bundle
Bundle: 1 archivo, 9 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add vercel/next.js --skill write-api-reference --agent claude-code
# Cursor
npx -y skills add vercel/next.js --skill write-api-reference --agent cursor
# Codex
npx -y skills add vercel/next.js --skill write-api-reference --agent codex
# Gemini CLI
npx -y skills add vercel/next.js --skill write-api-reference --agent gemini
# Windsurf
npx -y skills add vercel/next.js --skill write-api-reference --agent windsurf
# Cline
npx -y skills add vercel/next.js --skill write-api-reference --agent cline
```

## Qué hace

- Produce páginas de referencia de API de Next.js: funciones, componentes, convenciones de archivo, directivas y opciones de configuración
- Genera un `.mdx` con frontmatter YAML, ejemplo de uso, sección de referencia, notas de comportamiento y ejemplos
- Incluye la sección de historial de versiones y las reglas de estilo
- Parte del código fuente de Next.js, de páginas de referencia existentes o de una especificación del usuario

## Cuándo usarla

- Se pide escribir, crear o redactar una página de referencia de API
- Se trabaja en rutas como `docs/01-app/03-api-reference/`
- Se mencionan referencia de API, props, parámetros, retornos o firma

## Qué la activa

- "Escribe la referencia de API de esta función"
- "Documenta las props de este componente"
- "Crea la página de referencia de esta opción de configuración"

## Archivos

- SKILL.md — 9 KB

## SKILL.md

Reproducido tal cual desde vercel/next.js bajo MIT. Esta sección es el documento original y está en inglés.

# Writing API Reference Pages

## Goal

Produce an API reference page that documents a single API surface (function, component, file convention, directive, or config option). The page should be concise, scannable, and example-driven.

Each page documents **one API**. If the API has sub-methods (like `cookies.set()`), document them on the same page. If two APIs are independent, they get separate pages.

## Structure

Identify which category the API belongs to, then follow the corresponding template.

### Categories

1. **Function** (`cookies`, `fetch`, `generateStaticParams`): signature, params/returns, methods table, examples
2. **Component** (`Link`, `Image`, `Script`): props summary table, individual prop docs, examples
3. **File convention** (`page`, `layout`, `route`): definition, code showing the convention, props, behavior, examples
4. **Directive** (`use client`, `use cache`): definition, usage, serialization/boundary rules, reference
5. **Config option** (`basePath`, `images`, etc.): definition, config code, behavioral sections

### Template

````markdown
---
title: {API name}
description: {API Reference for the {API name} {function|component|file convention|directive|config option}.}
---

{One sentence defining what it does and where it's used.}

```tsx filename="path/to/file.tsx" switcher
// Minimal working usage
```

```jsx filename="path/to/file.js" switcher
// Same example in JS
```

## Reference

{For functions: methods/params table, return type.}
{For components: props summary table, then `#### propName` subsections.}
{For file conventions: `### Props` with `#### propName` subsections.}
{For directives: usage rules and serialization constraints.}
{For config: options table or individual option docs.}

### {Subsection name}

{Description + code example + table of values where applicable.}

## Good to know

- {Default behavior or implicit effects.}
- {Caveats, limitations, or version-specific notes.}
- {Edge cases the developer should be aware of.}

## Examples

### {Example name}

{Brief context, 1-2 sentences.}

```tsx filename="path/to/file.tsx" switcher
// Complete working example
```

```jsx filename="path/to/file.js" switcher
// Same example in JS
```

## Version History

| Version  | Changes         |
| -------- | --------------- |
| `vX.Y.Z` | {What changed.} |
````

**Category-specific notes:**

- **Functions**: Lead with the function signature and `await` if async. Document methods in a table if the return value has methods (like `cookies`). Document options in a separate table if applicable.
- **Components**: Start with a props summary table (`| Prop | Example | Type | Required |`). Then document each prop under `#### propName` with description, code example, and value table where useful.
- **File conventions**: Show the default export signature with TypeScript types. Document each prop (`params`, `searchParams`, etc.) under `#### propName` with a route/URL/value example table.
- **Directives**: No `## Reference` section. Use `## Usage` instead, showing correct placement. Document serialization constraints and boundary rules.
- **Config options**: Show the `next.config.ts` snippet. Use subsections for each behavioral aspect.

## Rules

1. **Lead with what it does.** First sentence defines the API. No preamble.
2. **Show working code immediately.** A minimal usage example appears right after the opening sentence, before `## Reference`.
3. **Use `switcher` for tsx/jsx pairs.** Always include both. Always include `filename="path/to/file.ext"`.
4. **Use `highlight={n}` for key lines.** Highlight the line that demonstrates the API being documented.
5. **Tables for simple APIs, subsections for complex ones.** If a prop/param needs only a type and one-line description, use a table row. If it needs a code example or multiple values, use a `####` subsection.
6. **Behavior section uses `> **Good to know**:`or`## Good to know`.** Use the blockquote format for brief notes (1-3 bullets). Use the heading format for longer sections. Not "Note:" or "Warning:".
7. **Examples section uses `### Example Name` subsections.** Each example solves one specific use case.
8. **Version History table at the end.** Include when the API has changed across versions. Omit for new APIs.
9. **No em dashes.** Use periods, commas, or parentheses instead.
10. **Mechanical, observable language.** Describe what happens, not how it feels. "Returns an object" not "gives you an object".
11. **Link to related docs with relative paths.** Use `/docs/app/...` format.
12. **No selling or justifying.** No "powerful", "easily", "simply". State what the API does.

| Don't                                                   | Do                                                                                          |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| "This powerful function lets you easily manage cookies" | "`cookies` is an async function that reads HTTP request cookies in Server Components"       |
| "You can conveniently access..."                        | "Returns an object containing..."                                                           |
| "The best way to handle navigation"                     | "`<Link>` extends the HTML `<a>` element to provide prefetching and client-side navigation" |

13. **Bridge new framework terms with legacy or generic vocabulary.** When the API renames or differentiates from a prior concept (Pages-era term, generic web term, REST vocabulary), include one such synonym in the frontmatter `description` and once in prose. Example: `description: "Use Dynamic Segments to read URL parameters and generate routes from dynamic data."` mentions "URL parameters" alongside "Dynamic Segments". One synonym, folded into natural prose. No separate "Synonyms" or "Also known as" section, no keyword stuffing. Goal: preserve discoverability for users still searching the old vocabulary even when the framework has moved on.

| Don't                              | Do                                                                                   |
| ---------------------------------- | ------------------------------------------------------------------------------------ |
| "Learn how to use Route Handlers"  | "Build API endpoints with Route Handlers, the App Router replacement for API Routes" |
| "Configure dynamic route segments" | "Read URL parameters from dynamic route segments"                                    |

## Workflow

1. **Ask for reference material.** Ask the user if they have any RFCs, PRs, design docs, or other context that should inform the doc.
2. **Identify the API category** (function, component, file convention, directive, config).
3. **Research the implementation.** Read the source code to understand params, return types, edge cases, and defaults.
4. **Check e2e tests.** Search `test/` for tests exercising the API to find real usage patterns, edge cases, and expected behavior.
5. **Check existing related docs** for linking opportunities and to avoid duplication.
6. **Write using the appropriate category template.** Follow the rules above.
7. **Review against the rules.** Verify: one sentence opener, immediate code example, correct `switcher`/`filename` usage, tables vs subsections, "Good to know" format, no em dashes, mechanical language.

## References

Read these pages in `docs/01-app/03-api-reference/` before writing. They demonstrate the patterns above.

- `04-functions/cookies.mdx` - Function with methods table, options table, and behavior notes
- `03-file-conventions/page.mdx` - File convention with props subsections and route/URL/value tables
- `02-components/link.mdx` - Component with props summary table and detailed per-prop docs
- `01-directives/use-client.mdx` - Directive with usage section and serialization rules
- `04-functions/fetch.mdx` - Function with troubleshooting section and version history

## Dónde encaja

- Categoría: [Documentos](https://skillsagentes.com/categorias/documentos.md) — Lee, escribe y transforma archivos PDF, DOCX, XLSX y PPTX.
- Creador: [vercel](https://skillsagentes.com/creators/vercel.md) — 36 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Next Cache Components Adoption](https://skillsagentes.com/skills/vercel/next.js/next-cache-components-adoption.md): Activa Cache Components en una app de Next.js y resuelve las rutas bloqueantes que aparecen. Úsalo para adoptar o migrar, activar el flag cacheComponents o decidir entre excluir rutas y arreglarlas.
- [Next Cache Components Optimizer](https://skillsagentes.com/skills/vercel/next.js/next-cache-components-optimizer.md): Lleva una ruta de Next.js a navegación instantánea bajo Cache Components o PPR mediante un bucle agéntico: codifica el objetivo como un e2e instant() en rojo y lo trabaja hasta verde, ruta a ruta.
- [Next Partial Prefetching Adoption](https://skillsagentes.com/skills/vercel/next.js/next-partial-prefetching-adoption.md): Activa Partial Prefetching en una app de Next.js y resuelve las insights que surgen: audita los Link con prefetch, activa partialPrefetching y opta por rutas con prefetch = 'partial'.
- [Next Dev Loop](https://skillsagentes.com/skills/vercel/next.js/next-dev-loop.md): Verifica el comportamiento en runtime de Next.js tras editar código de la aplicación. Combina /_next/mcp, la visión de Next.js, con agent-browser, la del navegador. Requiere un next dev en marcha.
- [Gh Stack](https://skillsagentes.com/skills/vercel/next.js/gh-stack.md): Gestiona PRs apilados y parte el trabajo en ramas revisables con gh-stack: creación, visualización, edición, push, envío, sincronización, rebase, merge y checkout.

## Skills relacionadas

- [Update Docs](https://skillsagentes.com/skills/vercel/next.js/update-docs.md): Flujo guiado para actualizar la documentación de Next.js según los cambios de código. Úsalo al preguntar qué documentación hace falta, sincronizar docs con código o documentar una funcionalidad.
- [Write Guide](https://skillsagentes.com/skills/vercel/next.js/write-guide.md): Genera guías técnicas que enseñan casos de uso reales con ejemplos progresivos: markdown con frontmatter YAML, introducción, de dos a cuatro pasos y una sección de siguientes pasos.
- [Authoring Skills](https://skillsagentes.com/skills/vercel/next.js/authoring-skills.md): Cómo crear y mantener skills de agente en .agents/skills/. Úsalo al crear un SKILL.md, escribir descripciones, elegir campos de frontmatter o decidir qué va en un skill y qué en AGENTS.md.
- [Backport Pr](https://skillsagentes.com/skills/vercel/next.js/backport-pr.md): Lleva un pull request fusionado de Next.js desde canary a una rama de release anterior como next-16-2: localiza el commit, crea la rama, hace cherry-pick, valida y abre el PR.
- [Create Pr](https://skillsagentes.com/skills/vercel/next.js/create-pr.md): Crea ramas, commits, pushes y pull requests de GitHub para Next.js. Cubre la plantilla de PR, el formato de --body, las ramas codex/ y las directivas de git de la app Codex.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)