# Write Guide

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

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

Repositorio: https://github.com/vercel/next.js
Autor: vercel
Licencia: MIT
Actualizado: hace 3 meses
Coste de contexto: 130 tok instalada, 1.6k tok al activarse, 1.6k tok con todos los archivos del bundle
Bundle: 1 archivo, 6 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-guide --agent claude-code
# Cursor
npx -y skills add vercel/next.js --skill write-guide --agent cursor
# Codex
npx -y skills add vercel/next.js --skill write-guide --agent codex
# Gemini CLI
npx -y skills add vercel/next.js --skill write-guide --agent gemini
# Windsurf
npx -y skills add vercel/next.js --skill write-guide --agent windsurf
# Cline
npx -y skills add vercel/next.js --skill write-guide --agent cline
```

## Qué hace

- Genera guías técnicas que enseñan casos de uso reales mediante ejemplos progresivos
- Produce una guía en markdown con frontmatter YAML, introducción, de dos a cuatro pasos progresivos y una sección de siguientes pasos
- Parte de skills de funcionalidad, documentación de API, ejemplos de código existentes o una especificación del usuario

## Cuándo usarla

- Se pide escribir, crear o redactar una guía o un tutorial
- Se convierte documentación de funcionalidad, referencia de API o conocimiento de un skill en contenido de aprendizaje paso a paso

## Qué la activa

- "Escribe una guía de esta funcionalidad"
- "Convierte esta referencia de API en un tutorial"
- "Hazme una guía paso a paso de este caso de uso"

## Archivos

- SKILL.md — 6 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 Guides

## Goal

Produce a technical guide that teaches a real-world use case through progressive examples. Concepts are introduced only when the reader needs them.

Each guide solves **one specific problem**. Not a category of problems. If the outline has 5+ steps or covers multiple approaches, split it.

## Structure

Every guide follows this arc: introduction, example setup, 2-5 progressive steps, next steps.

Each step follows this loop: working code → new requirement → friction → explanation → resolution → observable proof.

Sections: introduction (no heading, 2 paragraphs max), `## Example` (what we're building + source link), `### Step N` (action-oriented titles, 2-4 steps), `## Next steps` (summary + related links).

Headings should tell a story on their own. If readers only saw the headings, they'd understand the guide's takeaway.

### Template

````markdown
---
title: {Action-oriented, e.g., "Building X" or "How to Y"}
description: {One sentence}
nav_title: {Short title for navigation}
---

{What the reader will accomplish and why it matters. The friction and how this approach resolves it. 2 paragraphs max.}

## Example

As an example, we'll build {what we're building}.

We'll start with {step 1}, then {step 2}, and {step 3}.

{Source code link.}

### Step 1: {Action-oriented title}

{Brief context, 1-2 sentences.}

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

{Explain what happens.}

{Introduce friction: warning, limitation, or constraint.}

{Resolution: explain the choice, apply the fix.}

{Verify the fix with observable proof.}

### Step 2: {Action-oriented title}

{Same pattern: context → code → explain → friction → resolution → proof.}

### Step 3: {Action-oriented title}

{Same pattern.}

## Next steps

You now know how to {summary}.

Next, learn how to:

- [Related guide 1]()
- [Related guide 2]()
````

### Workflow

1. **Research**: Check available skills for relevant features. Read existing docs for context and linking opportunities.
2. **Plan**: Outline sections. Verify scope (one problem, 2-4 steps). Each step needs a friction point and resolution.
3. **Write**: Follow the template above. Apply the rules below.
4. **Review**: Re-read the rules, verify, then present.

## Rules

1. **Progressive disclosure.** Start with the smallest working example. Introduce complexity only when the example breaks. Name concepts at the moment of resolution, after the reader has felt the problem. Full loop: working → new requirement → something breaks → explain why → name the fix → apply → verify with proof → move on.
2. **Show problems visually.** Console errors, terminal output, build warnings, slow-loading pages. "If we refresh the page, we can see the component blocks the response."
3. **Verify resolutions with observable proof.** Before/after comparisons, browser reloads, terminal output. "If we refresh the page again, we can see it loads instantly."
4. **One friction point per step.** If a step has multiple friction points, split it.
5. **Minimal code blocks.** Only the code needed for the current step. Collapse unchanged functions with `function Header() {}`.
6. **No em dashes.** Use periods, commas, or parentheses instead.
7. **Mechanical, observable language.** Describe what happens, not how it feels.
8. **No selling, justifying, or comparing.** No "the best way," no historical context, no framework comparisons.

| Don't                                                | Do                                                       |
| ---------------------------------------------------- | -------------------------------------------------------- |
| "creates friction in the pipeline"                   | "blocks the response"                                    |
| "needs dynamic information"                          | "depends on request-time data"                           |
| "requires dynamic processing"                        | "output can't be known ahead of time"                    |
| "The component blocks the response — causing delays" | "The component blocks the response. This causes delays." |

9. **Bridge new framework terms with legacy or generic vocabulary in `description` and intro.** Guides win or lose SERPs on the colloquial query (e.g. "next js form submission", "next js api endpoint", "next js error page"), not on the framework's preferred noun. When the guide covers a renamed or differentiated concept, include one synonym (Pages-era term, REST/web term, or industry-standard label) in the frontmatter `description` and once in the introduction. Fold into prose. No separate "Synonyms" or "Also known as" section.

| Don't                                            | Do                                                                                                            |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| "Learn how to use Route Handlers"                | "Build API endpoints (formerly API Routes) with Route Handlers"                                               |
| "Learn how to mutate data with Server Functions" | "Submit forms and update data with Server Functions, the App Router approach to form posts and API mutations" |

## References

Read these guides in `docs/01-app/02-guides/` before writing. They demonstrate the patterns above.

- `public-static-pages.mdx` — intro → example → 3 progressive steps → next steps. Concepts named at point of resolution. Problems shown with build output.
- `forms.mdx` — progressive feature building without explicit "Step" labels. Each section adds one capability.

## 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 Api Reference](https://skillsagentes.com/skills/vercel/next.js/write-api-reference.md): 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.
- [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)