# Authoring Skills

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

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

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

## Qué hace

- Explica cómo crear y mantener skills de agente en `.agents/skills/`
- Cubre los campos de frontmatter soportados y cómo escribir la descripción para que el skill se active bien
- Fija convenciones de nombres, de estructura y de archivos suplementarios
- Aclara qué contenido va en un skill y qué va en `AGENTS.md`, que se carga siempre

## Cuándo usarla

- Crear un SKILL.md nuevo
- Escribir la descripción de un skill o elegir campos de frontmatter
- Decidir si algo va en un skill o en AGENTS.md

## Qué la activa

- "Crea un skill nuevo para este flujo"
- "Mejora la descripción de este skill para que se active"
- "¿Esto va en el skill o en AGENTS.md?"

## Antes de instalar

- Es un skill interno del repositorio de Next.js y no es invocable por el modelo.

## Archivos

- SKILL.md — 4 KB

## SKILL.md

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

# Authoring Skills

Use this skill when creating or modifying agent skills in `.agents/skills/`.

## When to Create a Skill

Create a skill when content is:

- Too detailed for AGENTS.md (code templates, multi-step workflows, diagnostic procedures)
- Only relevant for specific tasks (not needed every session)
- Self-contained enough to load independently

Keep in AGENTS.md instead when:

- It's a one-liner rule or guardrail every session needs
- It's a general-purpose gotcha any agent could hit

## File Structure

```
.agents/skills/
└── my-skill/
    ├── SKILL.md          # Required: frontmatter + content
    ├── workflow.md        # Optional: supplementary detail
    └── examples.md        # Optional: referenced from SKILL.md
```

## Supported Frontmatter Fields

```yaml
---
name: my-skill # Required. Used for $name references and /name commands.
description: > # Required. How Claude decides to auto-load the skill.
  What this covers and when to use it. Include file names and keywords.
argument-hint: '<pr-number>' # Optional. Hint for expected arguments.
user-invocable: false # Optional. Set false to hide from / menu.
disable-model-invocation: true # Optional. Set true to prevent auto-triggering.
allowed-tools: [Bash, Read] # Optional. Tools allowed without permission.
model: opus # Optional. Model override.
context: fork # Optional. Isolated subagent execution.
agent: Explore # Optional. Subagent type (with context: fork).
---
```

Only use fields from this list. Unknown fields are silently ignored.

## Writing Descriptions

The `description` is the primary matching surface for auto-activation. Include:

1. **What the skill covers** (topic)
2. **When to use it** (trigger scenario)
3. **Key file names** the skill references (e.g. `config-shared.ts`)
4. **Keywords** a user or agent might mention (e.g. "feature flag", "DCE")

```yaml
# Too vague - won't auto-trigger reliably
description: Helps with flags.

# Good - specific files and concepts for matching
description: >
  How to add or modify Next.js experimental feature flags end-to-end.
  Use when editing config-shared.ts, config-schema.ts, define-env-plugin.ts.
```

## Content Conventions

### Structure for Action

Skills should tell the agent what to **do**, not just what to **know**:

- Lead with "Use this skill when..."
- Include step-by-step procedures
- Add code templates ready to adapt
- End with verification commands
- Cross-reference related skills in a "Related Skills" section

### Relationship to AGENTS.md

| AGENTS.md (always loaded)               | Skills (on demand)                                                     |
| --------------------------------------- | ---------------------------------------------------------------------- |
| One-liner guardrails                    | Step-by-step workflows                                                 |
| "Keep require() behind if/else for DCE" | Full DCE pattern with code examples, verification commands, edge cases |
| Points to skills via `$name`            | Expands on AGENTS.md rules                                             |

When adding a skill, also add a one-liner summary to the relevant AGENTS.md section with a `$skill-name` reference.

### Naming

- Short, descriptive, topic-scoped: `flags`, `dce-edge`, `react-vendoring`
- No repo prefix (already scoped by `.agents/skills/`)
- Hyphens for multi-word names

### Supplementary Files

For complex skills, use a hub + detail pattern:

```
pr-status-triage/
├── SKILL.md         # Overview, quick commands, links to details
├── workflow.md      # Prioritization and patterns
└── local-repro.md   # CI env matching
```

## Dónde encaja

- Categoría: [Herramientas para desarrolladores](https://skillsagentes.com/categorias/herramientas-desarrollo.md) — Skills que cambian cómo tu agente escribe, revisa y despliega código.
- 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

- [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.
- [Dce Edge](https://skillsagentes.com/skills/vercel/next.js/dce-edge.md): Patrones de require() seguros para eliminación de código muerto y restricciones del runtime edge. Úsalo al escribir require condicionales, proteger imports de Node o editar define-env-plugin.ts.
- [Flags](https://skillsagentes.com/skills/vercel/next.js/flags.md): Cómo añadir o modificar flags experimentales de Next.js de principio a fin: tipo, esquema zod, inyección en build, paso de variables en runtime y elección entre ramificar o generar variantes.
- [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 Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)