Anatomía de una skill

Ya tienes una skill funcionando. Ahora desmontamos sus piezas para que puedas construir skills serias: el frontmatter que controla su comportamiento, los ficheros de soporte que la hacen potente y el contexto dinámico que la alimenta con datos reales.

El frontmatter

Va entre --- al principio del SKILL.md. Todos los campos son opcionales salvo que recomiendes description:

---
name: mi-skill
description: Qué hace y cuándo usarla
disable-model-invocation: true
allowed-tools: Read Grep
argument-hint: "[issue-number]"
---

Los que más usarás:

Campo	Para qué
`description`	el disparador: cuándo aplica (lección anterior)
`disable-model-invocation`	`true` → solo la invocas tú (acciones con efectos)
`user-invocable`	`false` → solo la invoca Claude (conocimiento de fondo)
`allowed-tools`	tools que Claude puede usar sin pedir permiso mientras la skill está activa
`disallowed-tools`	tools que se quitan del modelo mientras la skill está activa (p.ej. `AskUserQuestion` en un loop autónomo)
`argument-hint`	pista de autocompletado, p.ej. `[filename] [format]`
`paths`	limita la activación automática a ciertos ficheros (como las reglas por ruta)
`model`	fuerza un modelo mientras la skill está activa

Ojo con allowed-tools: concede permiso, no lo restringe. Una skill del repo que se trae allowed-tools: Bash(git push *) puede darse a sí misma acceso amplio. Revisa las skills de un repo antes de confiar en él — por eso este curso va después del de permisos.

allowed-tools y disallowed-tools son las dos caras: uno pre-aprueba tools, el otro las retira del alcance de la skill. La restricción de disallowed-tools se levanta en cuanto mandas tu siguiente mensaje.

Ficheros de soporte

Una skill es un directorio, no solo el SKILL.md. Eso te deja sacar el material pesado fuera, para que no cargue en contexto hasta que haga falta:

mi-skill/
├── SKILL.md          # instrucciones principales (obligatorio)
├── reference.md      # doc detallada, se carga cuando se necesita
├── examples.md       # ejemplos de salida esperada
└── scripts/
    └── helper.py     # script que Claude ejecuta (no se "lee" en contexto)

Referencia esos ficheros desde el SKILL.md para que Claude sepa qué contienen y cuándo abrirlos:

## Recursos
- Detalles de la API: [reference.md](reference.md)
- Ejemplos: [examples.md](examples.md)

Mantén el SKILL.md por debajo de ~500 líneas y conciso: una vez invocada, su contenido se queda en contexto durante la sesión, así que cada línea es coste recurrente. Lo gordo, a ficheros aparte.

Contexto dinámico: !`comando`

Esto es lo que diferencia una skill de un prompt estático. La sintaxis !`<comando>` ejecuta un comando de shell antes de que Claude vea la skill, y sustituye la línea por su salida:

## Estado actual
- Rama: !`git branch --show-current`
- Tests: !`pnpm test --silent`

## Tu tarea
Con la info de arriba, ...

Claude no ejecuta esos comandos: los ve ya resueltos, como datos. Es preprocesado. Para varios comandos, usa un bloque con ```!.

Argumentos

Como en los comandos, $ARGUMENTS recibe todo lo que escribas tras el nombre; $0, $1… (o $ARGUMENTS[0], $ARGUMENTS[1]…) acceden por posición, con el índice desde 0; y puedes declarar nombres en el frontmatter (arguments: [issue, branch] → $issue, $branch). Envuelve en comillas los valores con espacios.

Qué llevas hasta aquí

El frontmatter controla disparador, quién invoca, tools permitidas y más.
Los ficheros de soporte sacan el material pesado fuera del SKILL.md.
!`comando` inyecta datos reales antes de que Claude lea la skill.

En la siguiente lección juntamos todo en una skill real end-to-end: tu segundo artefacto.

Fuente oficial: Skills

¿Quieres llevar la cuenta de las lecciones que has terminado?

Entrar para guardar progreso