← Volver al listado de tecnologías ← Índice de Agent Skills

Tu primer skill paso a paso

6 de agosto de 2026 Por: Artiko

agent-skillsplugins-de-agentesia-agentesquickstartskill-mdtutorial-practico

Tu primer skill paso a paso

Los tres capítulos anteriores describieron el formato. Este lo ejecuta. Al terminar vas a tener dos skills funcionando: el del quickstart oficial, reproducido tal cual para que puedas contrastar tu resultado contra la fuente, y uno propio más útil construido con los mismos principios. El trabajo real son cuatro movimientos —crear la carpeta, escribir SKILL.md, ponerlo donde el cliente lo descubre y comprobar que dispara—; todo lo demás es cómo verificar cada paso cuando algo no sale.

El recorrido completo

flowchart LR
    A["1. Crear carpeta<br/>nombre = name del skill"] --> B["2. Escribir SKILL.md<br/>frontmatter + cuerpo"]
    B --> C["3. Ubicarla donde<br/>el cliente escanea"]
    C --> D["4. Comprobar<br/>que fue descubierto"]
    D --> E["5. Probar el disparo<br/>con una consulta real"]
    E -->|"no dispara o<br/>dispara mal"| B

El bucle de retorno es el capítulo entero: escribir el archivo cuesta minutos, ajustarlo hasta que dispare cuando debe es el trabajo que sigue.

Paso 1: crear la carpeta

La especificación es corta en esto:

A skill is a directory containing, at minimum, a SKILL.md file.

Un skill es un directorio con, como mínimo, un archivo SKILL.md. Y una restricción normativa ata el nombre del directorio al del skill: el campo name debe (must, término original de la fuente) coincidir con el nombre del directorio padre.

Ese detalle es la causa más común de que un primer skill no aparezca en el catálogo: si la carpeta se llama rollDice y el frontmatter dice name: roll-dice, el skill está mal formado según la especificación, aunque algunos clientes lo carguen igual emitiendo un aviso. El skill del quickstart oficial se llama roll-dice, así que la carpeta se llama roll-dice:

mkdir -p .agents/skills/roll-dice

La estructura resultante:

.agents/skills/
- roll-dice/
  - SKILL.md

Un solo archivo. Los directorios scripts/, references/ y assets/ del capítulo de anatomía son convenciones opcionales; este skill no necesita ninguno.

Paso 2: escribir SKILL.md

Este es el contenido literal del quickstart oficial. El skill le da al agente la capacidad de tirar dados usando un generador de números aleatorios.

Archivo .agents/skills/roll-dice/SKILL.md:

---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.
---

To roll a die, use the following command that generates a random number from 1
to the given number of sides:

```bash
echo $((RANDOM % <sides> + 1))
```

```powershell
Get-Random -Minimum 1 -Maximum (<sides> + 1)
```

Replace `<sides>` with the number of sides on the die (e.g., 6 for a standard
die, 20 for a d20).

Eso es todo: un archivo, menos de 20 líneas. La propia documentación desglosa las tres partes:

name — un identificador corto del skill. Debe coincidir con el nombre de la carpeta.
description — le dice al agente cuándo usar este skill. Es el mecanismo por el que el agente decide si activarlo.
El cuerpo — las instrucciones que el agente sigue cuando el skill se activa. Aquí se le indica generar un número aleatorio con un comando de terminal, sustituyendo el número de caras que pidió el usuario.

Dos observaciones útiles para calibrar tus propios skills: el cuerpo no explica qué es un dado, solo el comando exacto y la sustitución que hay que hacer —todo lo que el modelo ya sabe queda fuera—, y la description enumera formas de pedirlo (“roll a die”, “d6”, “d20”, “roll dice”, “random dice roll”) en lugar de describir la implementación. Ese criterio se trabaja a fondo en el capítulo 6.

Paso 3: ubicar la carpeta donde el cliente la descubre

Aquí conviene una precisión que la propia fuente subraya. La guía de implementación para clientes dice, literalmente, que la especificación no manda dónde viven los directorios de skills; solo define qué va dentro de ellos.

While the Agent Skills specification does not mandate where skill directories live (it only defines what goes inside them), scanning .agents/skills/ means skills installed by other compliant clients are automatically visible to yours, and vice versa.

O sea: .agents/skills/ no es una regla del estándar, es la convención de interoperabilidad ampliamente adoptada para que un skill instalado por un cliente sea visible para los demás.

Personal frente a proyecto

La guía sugiere a los clientes escanear al menos dos ámbitos, cada uno en dos rutas:

Ámbito	Ruta	Propósito
Proyecto	`<proyecto>/.<tu-cliente>/skills/`	Ubicación nativa del cliente
Proyecto	`<proyecto>/.agents/skills/`	Interoperabilidad entre clientes
Usuario	`~/.<tu-cliente>/skills/`	Ubicación nativa del cliente
Usuario	`~/.agents/skills/`	Interoperabilidad entre clientes

Traducido a una decisión práctica: el skill de proyecto vive dentro del repositorio, se versiona con el código y viaja con él; es lo correcto para convenciones del proyecto —cómo se escriben los commits aquí, cómo se corre la suite de tests aquí—. El skill personal (de usuario) vive en tu directorio home y está disponible en todos tus proyectos; es lo correcto para tu forma de trabajar, no la del equipo.

Cuando dos skills comparten name, la convención que la guía describe como universal entre implementaciones existentes es que los skills de proyecto ganan sobre los de usuario. Dentro del mismo ámbito, cada cliente elige first-found o last-found, pero de forma consistente.

La misma guía añade una nota sobre rutas adicionales:

Some implementations also scan .claude/skills/ (both project-level and user-level) for pragmatic compatibility, since many existing skills are installed there.

.claude/skills/ aparece por compatibilidad pragmática con skills ya instaladas ahí, no porque forme parte del estándar. Otras ubicaciones que algunas implementaciones escanean: directorios ancestros hasta la raíz git, directorios XDG y rutas configuradas por el usuario.

Qué busca exactamente el escaneo

El criterio de descubrimiento es literal:

Within each skills directory, look for subdirectories containing a file named exactly SKILL.md.

Subdirectorios que contengan un archivo llamado exactamente SKILL.md. Ni skill.md, ni SKILL.markdown, ni un SKILL.md suelto en la raíz del directorio de skills sin su carpeta propia:

~/.agents/skills/
- pdf-processing/
  - SKILL.md  # descubierto
  - scripts/
    - extract.py
- data-analysis/
  - SKILL.md  # descubierto
- README.md   # ignorado, no es un directorio de skill

Para el quickstart, la ruta concreta es .agents/skills/roll-dice/SKILL.md relativa a la raíz del proyecto. La documentación oficial usa VS Code con GitHub Copilot y señala que VS Code busca skills en .agents/skills/ por defecto, con esta aclaración de alcance:

This tutorial uses VS Code, but Agent Skills are an open format. The same skill works in any compatible agent, including Claude Code and OpenAI Codex.

Dónde busca tu cliente sale de su propia documentación; el capítulo 11 recopila los enlaces.

Paso 4: comprobar que el skill fue descubierto

Antes de probar si dispara, comprueba que existe para el agente. Son verificaciones distintas: un skill puede estar bien descubierto y aun así no activarse porque su description no engancha.

Verificación del formato, sin cliente

La especificación documenta una biblioteca de referencia para validar:

skills-ref validate ./.agents/skills/roll-dice

Esto comprueba que el frontmatter de tu SKILL.md es válido y respeta las convenciones de nombres: longitud de name, minúsculas, guiones, coincidencia con el directorio padre, description no vacía y dentro de 1024 caracteres. No depende de ningún cliente. Ten presente su alcance: el README de skills-ref declara que la biblioteca está pensada solo para demostración y no para uso en producción. Es un validador del formato, no un runtime.

Verificación del catálogo, dentro del cliente

El quickstart oficial da el procedimiento para VS Code:

Abre tu proyecto en VS Code.
Abre el panel de Copilot Chat.
Selecciona el modo Agent en el desplegable de modos, abajo en el panel.
Escribe /skills para confirmar que roll-dice aparece en la lista. Si no aparece, revisa que el archivo esté en .agents/skills/roll-dice/SKILL.md relativo a la raíz del proyecto.
Pregunta: “Roll a d20”.

El paso 4 es la comprobación de descubrimiento. Cada cliente expone esa lista a su manera —un comando, un panel, un flag de depuración— pero la pregunta es siempre la misma: ¿aparece mi skill en el catálogo que el cliente le muestra al modelo? Si no aparece, el problema está en el descubrimiento, y las causas posibles son pocas:

Síntoma	Causa habitual
No aparece en la lista	La carpeta no está en una ruta escaneada por ese cliente
No aparece en la lista	El archivo no se llama exactamente `SKILL.md`
No aparece, sin mensaje de error	La `description` falta o está vacía: la guía sugiere omitir el skill en ese caso
No aparece, sin mensaje de error	El YAML es imparseable, por ejemplo dos puntos sin comillar dentro de un valor
Aparece con un aviso	El `name` no coincide con la carpeta, o supera 64 caracteres

Esa última fila describe la validación laxa que la guía recomienda a los clientes: avisar pero cargar igual ante problemas cosméticos, y saltar el skill solo cuando falta la description o el YAML no se puede parsear. Ese último caso merece un ejemplo, porque es el error más frecuente al escribir descripciones largas. Esto no es YAML válido:

# Los dos puntos rompen el parseo
description: Use this skill when: the user asks about PDFs

La guía sugiere a los clientes un fallback que entrecomille esos valores o los convierta a block scalars antes de reintentar, pero no todos lo implementan:

description: "Use this skill when: the user asks about PDFs"

Paso 5: verlo dispararse

Con el skill en el catálogo, pídele al agente: “Roll a d20”.

Lo esperado, según la documentación: el agente activa el skill roll-dice, puede pedir permiso para ejecutar un comando de terminal —hay que concedérselo—, ejecuta el comando y devuelve un número aleatorio entre 1 y 20.

La fuente incluye una advertencia honesta que conviene reproducir:

Tool-use reliability varies across models — some follow skill instructions and run commands consistently, while others may attempt to answer on their own. If the agent responds without running a terminal command, try selecting a different model from the model dropdown.

La fiabilidad del uso de herramientas varía entre modelos: algunos siguen las instrucciones y ejecutan los comandos de forma consistente, otros intentan responder por su cuenta. Si el agente responde sin ejecutar el comando, prueba con otro modelo. No es un defecto de tu skill, es una variable del entorno que conviene fijar antes de reescribir instrucciones.

Qué ocurrió por dentro

El quickstart lo describe en tres etapas, que son las mismas tres de la divulgación progresiva:

sequenceDiagram
    participant U as Usuario
    participant C as Cliente
    participant M as Modelo
    participant S as SKILL.md
    Note over C: Inicio de sesión
    C->>S: escanea directorios de skills
    S-->>C: name + description de roll-dice
    C->>M: catálogo con name y description
    Note over C,M: Etapa 1 · Discovery
    U->>M: "Roll a d20"
    M->>S: activa roll-dice y carga el cuerpo completo
    S-->>M: instrucciones del skill
    Note over M,S: Etapa 2 · Activation
    M->>C: ejecuta el comando con sides igual a 20
    C-->>U: número aleatorio entre 1 y 20
    Note over M,C: Etapa 3 · Execution

Discovery — al iniciar la sesión de chat, el agente escaneó los directorios de skills por defecto y encontró el tuyo. Leyó solo el name y la description, lo justo para saber cuándo podría ser relevante.
Activation — cuando preguntaste por tirar un dado, el agente hizo coincidir tu pregunta con la description del skill y cargó el cuerpo completo de SKILL.md en contexto.
Execution — el agente siguió las instrucciones del cuerpo, adaptando el comando de terminal al número de caras de tu petición.

Ese es el mecanismo de divulgación progresiva que permite al agente tener muchas skills disponibles sin cargar todas sus instrucciones por adelantado; el capítulo 1 lo introdujo.

Forzar la activación para probar

Depender de que el modelo decida activar el skill es lento para iterar. La guía de implementación establece que los usuarios deberían poder activarlo directamente:

Users should also be able to activate skills directly, without waiting for the model to decide. The most common pattern is a slash command or mention syntax (/skill-name or $skill-name) that the harness intercepts. The specific syntax is up to you.

El patrón más común es un comando con barra o una sintaxis de mención —/nombre-skill o $nombre-skill— que el harness intercepta. La sintaxis concreta la decide cada cliente, así que consulta la documentación del tuyo; el estándar no la fija.

La activación explícita separa dos preguntas que se confunden todo el tiempo:

flowchart TD
    A["El skill no produce<br/>el resultado esperado"] --> B{"¿Forzando la activación<br/>funciona bien?"}
    B -->|Sí| C["El problema está en la description<br/>→ capítulo 6"]
    B -->|No| D["El problema está en el cuerpo<br/>→ capítulo 5"]

Si al forzarlo el skill hace exactamente lo que querías, tu cuerpo está bien y lo que falla es el disparo. Si al forzarlo tampoco funciona, no toques la description todavía: el problema son las instrucciones.

El ciclo editar-recargar-probar

Editar el archivo no basta. Qué necesita recargarse depende de qué parte tocaste, y eso sale directamente del modelo de divulgación progresiva.

flowchart TD
    A["Editas SKILL.md"] --> B{"¿Qué cambiaste?"}
    B -->|"name o description"| C["Se cargan al inicio de sesión<br/>→ reinicia la sesión"]
    B -->|"cuerpo Markdown"| D["Se carga al activar<br/>→ puede bastar una activación nueva"]
    B -->|"ruta o nombre de carpeta"| E["Cambia el descubrimiento<br/>→ reinicia la sesión"]
    C --> F["Comprueba el catálogo"]
    E --> F
    D --> G["Fuerza la activación y prueba"]
    F --> G
    G -->|"no es lo esperado"| A

El razonamiento detrás del diagrama:

name y description se cargan al arranque, para todos los skills. La especificación lo dice así: los campos name y description se cargan al inicio para todos los skills disponibles. Si cambias la description, la sesión actual sigue viendo la anterior. Reinicia.
El cuerpo se carga al activar. Ahora bien, cuándo lee el cuerpo el cliente es una decisión suya: la guía reconoce como válidas tanto leerlo en el descubrimiento (activación más rápida) como leerlo en la activación (menos memoria agregada y recoge cambios del archivo). En un cliente del primer tipo, editar el cuerpo sin reiniciar no cambia nada.
Ante la duda, reinicia la sesión. Es más barato que depurar un cambio que el agente nunca vio.

Hay un tercer factor que enmascara resultados: la guía recomienda a los clientes deduplicar activaciones para no reinyectar el mismo skill dos veces en una conversación. Si lo activaste, lo editaste y lo vuelves a activar en la misma sesión, puede que el cliente reutilice el contenido anterior. Este criterio de aislamiento reaparece, formalizado, en el capítulo 9: cada corrida de evaluación debería empezar con un contexto limpio.

Segundo ejemplo: un skill propio, más útil

roll-dice enseña el mecanismo pero no resuelve nada real. Vamos a construir uno con los mismos principios —un solo archivo, cuerpo corto, description que dice qué y cuándo— pero que valga la pena tener instalado: mantener el CHANGELOG.md de un proyecto. Tarea repetitiva, formato fijo, convenciones que el modelo no puede adivinar y errores típicos que cuestan revertir. Exactamente el perfil donde un skill aporta.

Estructura:

.agents/skills/
- changelog-entry/
  - SKILL.md

Archivo .agents/skills/changelog-entry/SKILL.md:

---
name: changelog-entry
description: Redacta y agrega entradas al CHANGELOG.md del proyecto siguiendo el formato Keep a Changelog. Úsala cuando haya que documentar un cambio recién hecho, preparar las notas de una versión, actualizar el changelog o decidir qué escribir sobre un commit o un pull request, incluso si el usuario no menciona la palabra changelog.
---

Las entradas van siempre en la sección `## [Unreleased]`, arriba del todo, nunca
en una versión ya publicada.

## Procedimiento

1. Lee el `CHANGELOG.md` actual para copiar su estilo: longitud de las líneas,
   uso del imperativo, si se referencian issues.
2. Reúne los cambios pendientes desde la última etiqueta:

```bash
git log --oneline "$(git describe --tags --abbrev=0)"..HEAD
```

3. Clasifica cada cambio en una de estas seis categorías, en este orden:
   `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`.
4. Escribe una línea por cambio visible para quien usa el proyecto, con la
   plantilla de abajo.
5. Si `## [Unreleased]` no existe, créala sobre la última versión publicada.
6. Muestra el diff propuesto antes de escribir el archivo.

## Plantilla de entrada

```markdown
## [Unreleased]

### Added
- Descripción en imperativo de la capacidad nueva (#123)

### Fixed
- Descripción del comportamiento que estaba mal y ahora no (#124)
```

## Gotchas

- Un refactor interno sin efecto observable no genera entrada. Si nadie fuera
  del repositorio nota el cambio, no va al changelog.
- Nunca reordenes ni reescribas secciones de versiones ya publicadas: son
  historial, no borrador.
- Las categorías vacías se omiten; no dejes un `### Removed` sin ítems.
- Si `git describe` falla porque no hay ninguna etiqueta, usa el rango completo
  con `git log --oneline` y avísalo en la respuesta.
- Los mensajes de commit no sirven tal cual: están escritos para quien programa,
  no para quien usa el proyecto. Reescríbelos.

Por qué está escrito así

Cada decisión de ese archivo tiene una razón que reaparecerá en los capítulos siguientes:

Decisión	Principio
La `description` dice qué hace y cuándo usarla	La especificación pide (should) ambas cosas
Cierra con “incluso si el usuario no menciona la palabra changelog”	Listar contextos explícitos, sin exigir que el usuario nombre el dominio
Procedimiento numerado con un paso de validación al final	Patrón de checklist para flujos multi-paso
Sección `## Gotchas`	Hechos del entorno que desafían suposiciones razonables
Plantilla de salida concreta en vez de describir el formato en prosa	Los agentes hacen buen pattern-matching contra estructuras concretas
Un comando único y fijado, no un menú de alternativas	Dar defaults, no menús
No explica qué es git ni qué es un changelog	Añade lo que al agente le falta, omite lo que ya sabe

El paso 6 del procedimiento —mostrar el diff antes de escribir— es una versión mínima del patrón plan-validate-execute, apropiada cuando la operación modifica un archivo con historial.

Probarlo

El ciclo es el mismo del quickstart:

skills-ref validate ./.agents/skills/changelog-entry para descartar problemas de formato.
Reinicia la sesión y confirma que aparece en el catálogo del cliente.
Fuerza la activación y pide: “documenta en el changelog lo que llevamos desde la última release”. Si el resultado es bueno, el cuerpo funciona.
Sesión nueva, sin forzar, con una consulta que no nombre el dominio: “acabo de mergear el fix del login, ¿hay que anotar algo antes de tagear?”. Si el skill dispara solo, la description funciona.

El paso 4 es la prueba interesante. La documentación advierte que los agentes suelen consultar skills solo para tareas que requieren conocimiento o capacidades más allá de lo que pueden resolver solos: una petición simple de un paso puede no disparar un skill aunque la description calce perfecto. Convertir esa intuición en una medición repetible es el trabajo del capítulo 6.

Qué falta y dónde está

Tu skill funciona. Los siguientes cortes, en orden de utilidad: calibrar detalle y libertad (capítulo 5), medir el disparo con un set de consultas (capítulo 6), sacar hacia scripts/ la lógica que el agente reinventa cada vez (capítulo 7), partir un SKILL.md que creció hacia references/ y assets/ (capítulo 8) y repartirlo al equipo (capítulo 10).

Si vas a empaquetarlo junto con servidores MCP y otros componentes, el curso hermano de Agent Plugins cubre ese formato. Y para leer skills reales antes de escribir las tuyas, el curso de Google Skills recorre un catálogo oficial con más de cien skills publicadas.

Errores del primer intento

Un resumen de lo que se rompe con más frecuencia, con la corrección directa:

Error	Corrección
`name` distinto del nombre de la carpeta	Renombra uno de los dos; el estándar exige que coincidan
`name` con mayúsculas, guion inicial o final, o `--`	Solo minúsculas, dígitos y guiones simples
Archivo llamado `skill.md`	Debe llamarse exactamente `SKILL.md`
`SKILL.md` suelto en `.agents/skills/`	Necesita su propia subcarpeta
`description` con dos puntos sin comillar	Entrecomilla el valor o usa un escalar de bloque
`description` tipo “Ayuda con X”	Escribe qué hace y cuándo usarla, con las palabras del usuario
Editas y nada cambia	Reinicia la sesión: el catálogo se carga al arranque
Dispara donde no debe	No es un problema del cuerpo; acota la `description`
El agente responde sin ejecutar el comando	Prueba otro modelo antes de reescribir el skill
Editas el cuerpo y el resultado no cambia	El cliente puede estar deduplicando la activación; sesión nueva

Resumen

Un skill es un directorio con un SKILL.md; el name del frontmatter debe coincidir con el nombre de ese directorio.
El skill del quickstart oficial, roll-dice, cabe en menos de veinte líneas: dos campos de frontmatter y un comando de terminal en el cuerpo.
La especificación no manda dónde viven los directorios de skills. .agents/skills/ es la convención de interoperabilidad ampliamente adoptada; cada cliente añade además su propia ubicación nativa, y algunos escanean .claude/skills/ por compatibilidad pragmática.
Ámbito de proyecto para convenciones del repositorio, ámbito de usuario para tu forma de trabajar. Ante colisión de nombres, la convención universal es que proyecto gana sobre usuario.
El descubrimiento busca subdirectorios con un archivo llamado exactamente SKILL.md. Se comprueba con skills-ref validate para el formato y con el catálogo del cliente para la visibilidad.
Los clientes deberían ofrecer activación explícita por el usuario, típicamente con un comando con barra o una mención de sintaxis propia. Sirve para separar un fallo de description de un fallo de instrucciones.
name y description se cargan al inicio de sesión y el cuerpo al activar: tras editar el frontmatter, reinicia la sesión. Y si el agente no ejecuta el comando, prueba otro modelo antes de tocar el skill: la fiabilidad del uso de herramientas varía entre modelos.

Siguiente: Escribir buenas instrucciones: alcance y calibración