Skills

1. ¿Qué son las Skills?

Las skills son una especie de super-prompts reutilizables: archivos de instrucciones que le dicen al agente cómo hacer tareas específicas de forma experta. Funcionan como recetas o micro-manuales de procedimiento que el agente consulta automáticamente cuando detecta que una tarea lo requiere.

Por ejemplo, una skill sencilla podría ser esta:

---
name: chistako
description: >
  Usar cuando el usuario cuente un chiste, haga un juego de palabras,
  o diga "te cuento un chistako".
---

# Chistako Detector

Responde únicamente: **LOL**

Sin activarla, si le decimos esto al agente:

Chistako: van dos por la calle y se cayó el de en medio

Responderá algo estándar, como:

Jeje, el clásico chiste de lógica absurda:
Si van dos por la calle... no hay ninguno en el medio. No puede caerse el que no existe.
Es el chiste malo por excelencia. Simple pero efectivo.

Pero si la activamos, ante la misma cuestión responderá con un magnífico:

LOL

El límite es la imaginación. Por ejemplo, una skill para que revise el código de un archivo cuando se lo pidamos:

---
name: code-review
description: >
  Usar cuando el usuario pida revisar código. Activar también si
  pega un fragmento y dice "qué te parece" o "está bien esto".
---

# Code Review

Revisa el código en este orden:

1. **Correctitud** — ¿hace lo que se supone?
2. **Edge cases** — ¿qué puede explotar?
3. **Legibilidad** — ¿se entiende sin comentarios?
4. **Performance** — solo si hay algo obvio.
5. **Seguridad** — inputs sin validar, secretos expuestos, etc.

Sé directo. No alabes lo que está bien, solo señala lo que hay que cambiar.

2. Anatomía de una skill

2.1. Ubicación

El formato SKILL.md es un estándar abierto (agentskills.io). En teoría, el mismo archivo funciona en Claude Code, Cursor, Codex, VS Code Copilot y Gemini CLI sin modificaciones. Según el agente irán en un sitio u otro, pero la dirección hacia la que converge todo es:

~/.agents/skills/

En Claude, de momento, van aquí:

~/.claude/skills/[nombre-skill]

Y dentro de ese directorio, la estructura sería:

.claude/skills/
-- nombre-skill/
    -- SKILL.md          # obligatorio
    -- references/       # docs que Claude carga bajo demanda
    -- scripts/          # código ejecutable
    -- assets/           # plantillas, fuentes, iconos

El único archivo obligatorio es SKILL.md.

2.2. Estructura

Un SKILL.md tiene dos partes separadas por ---:

---
name: mi-skill
description: Hace X
---

# Instrucciones
Haz esto primero...

La parte de arriba se llama frontmatter: un bloque de metadatos al principio del archivo. No es exclusivo de skills; lo verás en posts de blog (Jekyll, Hugo), documentación (Docusaurus) y Markdown en general. Siempre tiene la misma forma: datos entre ---, contenido debajo. El frontmatter se escribe en YAML, un formato de datos legible por humanos. El cuerpo se escribe en Markdown libre.

Hay dos parámetros obligatorios (hay otros opcionales que ya veremos):

• name: identificador único. Se convierte en /nombre como slash command.
• description: lo único que lee el agente para decidir si activar la skill.

En la parte inferior van las instrucciones que Claude seguirá cuando la skill se active. Sin restricciones de formato, aunque como veremos no debería superar las 500 líneas.

Antes de seguir, te invito a que escribas una primera skill con lo que sea y la pruebes. ¿Está condicionada la respuesta del modelo por las instrucciones que le estás pasando?

Dicho esto, vamos al núcleo de la skill: la carga bajo demanda.

3. Por qué importa la economía del token

Cuando trabajas con un LLM, todo lo que existe para él en un momento dado cabe en una ventana de contexto. No hay disco duro, no hay memoria persistente, solo ese espacio finito medido en tokens.

Esto tiene una consecuencia directa: meter información en el contexto tiene un coste. No solo económico (tokens = dinero en la API), sino de calidad. La atención no se distribuye de forma uniforme a lo largo del contexto: los LLMs prestan más atención a los tokens al principio y al final, con una caída significativa en el medio. La precisión puede caer más de un 30% cuando la información relevante está enterrada en el centro del input.

Y hay algo más. Parece ser que los modelos pueden desarrollar lo que se conoce como context anxiety: tomar atajos y dejar tareas incompletas cuando creen que se están quedando sin espacio, incluso cuando tienen margen de sobra. El modelo no colapsa limpiamente; simplemente empieza a comportarse peor sin avisar.

La conclusión práctica es que un contexto enorme no siempre es un mejor contexto. Más información puede significar más distracción y un coste añadido que no compensa. Es el problema que vimos cuando hablamos de los MCPs, y que vienen a solucionar las skills.

4. Progressive disclosure

Las skills están diseñadas explícitamente para resolver la economía del token mediante lo que se llama progressive disclosure: cargar solo lo que hace falta, cuando hace falta.

Al arrancar una sesión, el agente solo tiene en contexto el name y la description de cada skill: unas pocas líneas por skill. El cuerpo completo, los scripts, las referencias… nada de eso existe en contexto hasta que se necesita. Aunque tengas 20 skills instaladas, el coste en tokens es mínimo.

Cuando una skill se activa, Claude carga su SKILL.md. Si ese archivo referencia otros documentos, solo carga los relevantes para esa tarea concreta. Una skill con 10 archivos de referencia no mete los 10 en contexto; solo uno cuando toque. ¿Y cómo sabe cuál toca? Como vimos, el que encaje la description con lo que se está pidiendo.

Por ejemplo, esta skill solo se cargará cuando hagas un commit:

description: >
  Usar cuando el usuario quiera generar un mensaje de commit.
  Activar si pega un diff, una lista de archivos cambiados, o describe
  los cambios con sus propias palabras. También si dice "qué pongo en
  el commit", "escríbeme el commit" o "mensaje para git". Activar
  incluso si no menciona git explícitamente pero el contexto implica
  que está a punto de hacer un commit.

(El > es sintaxis YAML para texto multilínea: le dice al parser que junte todas las líneas en una sola cadena, ignorando los saltos de línea.)

Resumiendo: al arrancar la sesión, el agente carga en contexto únicamente el name y la description de cada skill disponible. El cuerpo del SKILL.md no existe para el agente hasta que decide activarla. Cuando llega una petición, el agente compara lo que el usuario pide contra esas descripciones. Si hay match, lee el SKILL.md completo y sigue sus instrucciones. Si no, responde directamente sin consultar ninguna skill.

Esto significa que la descripción es el único mecanismo de activación. Un cuerpo brillante con instrucciones perfectas no sirve de nada si la descripción no lo activa.

La diferencia con los MCP es importante. No hacen lo mismo. MCP le da a los agentes herramientas —capacidad de ejecutar acciones: consultar una base de datos, enviar un mensaje, llamar a una API—. Las skills, en cambio, le dan conocimiento y procedimientos: instrucciones sobre cómo hacer algo bien, qué pasos seguir, qué convenciones respetar, qué errores evitar.

Una analogía culinaria: MCP es la cocina, con cuchillos, fogones e ingredientes. Una skill es la receta que dice al agente cómo usarlos. Se complementan: puedes tener una skill que defina el flujo de trabajo de un code review y que dentro de ese flujo llame a herramientas MCP para consultar el historial de Jira. Pero son capas distintas con responsabilidades distintas.

5. ¿Cómo escribir una buena description?

Alguien podría preguntarse: si el agente solo se activa si machea el prompt con la descripción, ¿puede ocurrir que deje de usar una skill por error? Sí. Es lo que se conoce como undertriggering. Claude tiene cierto sesgo hacia resolver las cosas por su cuenta. Si una tarea le parece manejable sin consultar una skill, no la consulta. Esto es especialmente problemático en tareas simples o cuando la descripción es confusa.

Algunos consejos para que las descripciones funcionen mejor.

Cubre sinónimos y variantes. El usuario no siempre usará las mismas palabras. Si tu skill genera commits, la descripción debe cubrir todas las formas en que alguien puede pedirlo:

description: >
  Usar cuando el usuario quiera generar un mensaje de commit.
  Activar si pega un diff, una lista de cambios, o dice "qué pongo
  en el commit", "escríbeme el commit" o "mensaje para git".

Cubre frases vagas.

description: >
  Activar incluso si el usuario no menciona commits explícitamente
  pero pega código con cambios y pregunta cómo documentarlo.

Define los límites. Decirle al agente cuándo NO usar la skill es tan importante como decirle cuándo sí.

description: >
  No usar para PRs ni changelogs, esos tienen su propia skill.

Sé imperativo.

# Débil
description: Puede ayudar con commits.

# Fuerte
description: Usar siempre que el usuario necesite generar un commit.

En síntesis: hay que indicarle de la forma más precisa posible al agente cuándo debe activar una skill.

6. Archivos complementarios

El SKILL.md es el punto de entrada obligatorio, pero una skill puede incluir archivos adicionales organizados en tres carpetas con propósitos distintos.

6.1. references/

Documentos que el agente carga bajo demanda cuando la tarea lo requiere. El SKILL.md debe indicar explícitamente cuándo leerlos:

## Tokens de diseño
Lee siempre `references/tokens.css` antes de generar o revisar código relacionado con los estilos.

El agente no los carga todos por defecto, solo el que corresponde. Esto permite tener skills con mucho contenido sin inflar el contexto innecesariamente. Se pueden usar, por ejemplo, para:

• Flujos alternativos según el tipo de input.
• Documentación técnica de referencia.
• Tokens de diseño, esquemas de base de datos, convenciones del equipo.
• Cualquier contenido que solo aplica a algunos casos.

6.2. scripts/

Código ejecutable para pasos deterministas o repetitivos. En lugar de instrucciones en prosa que el agente puede interpretar de forma inconsistente, un script produce siempre el mismo resultado.

Por ejemplo, con una skill de design-tokens, un script escanea un archivo CSS y detecta valores hardcodeados:

design-tokens/
-- SKILL.md
-- references/
    -- tokens.css
-- scripts/
    -- check_hardcoded.py

# check_hardcoded.py
import re
import sys

file_path = sys.argv[1]

patterns = [
    (r'#[0-9a-fA-F]{3,6}', 'color hex'),
    (r'rgb\(.*?\)', 'color rgb'),
    (r'rgba\(.*?\)', 'color rgba'),
    (r'\b\d+px\b', 'tamaño en px'),
    (r'\b\d+rem\b', 'tamaño en rem'),
]

with open(file_path) as f:
    lines = f.readlines()

for i, line in enumerate(lines, 1):
    for pattern, label in patterns:
        if re.search(pattern, line):
            print(f"Línea {i} [{label}]: {line.strip()}")

Y en el SKILL.md:

## Revisar código existente
Ejecuta el script para detectar valores hardcodeados:
`python scripts/check_hardcoded.py <archivo.css>`

Usa el output para señalar cada problema y sugerir
el token correspondiente de `references/tokens.css`.

Importante: el agente ejecuta el script y trabaja con el output. El código del script nunca entra en contexto, solo el resultado. Esto es especialmente útil para:

• Parsear o transformar archivos.
• Validar estructuras antes de procesarlas.
• Operaciones con cálculos o conversiones.
• Procesos idempotentes (ante los mismos inputs, siempre devuelve el mismo resultado).

6.3. assets/

Archivos estáticos que el agente usa como base para generar output: plantillas, fuentes, iconos, imágenes de referencia.

mi-skill/
    -- assets/
        -- template.docx

7. Cómo mejorar una skill

Escribir la primera versión de una skill es fácil. Que funcione bien en la práctica es otro asunto. El proceso es iterativo:

Borrador > Prueba > Revisión > Ajuste > repetir.

a. Borrador. Escribe la primera versión sin obsesionarte con que sea perfecta. Una skill simple que funciona el 70% de los casos es mejor punto de partida que una skill perfecta que nunca terminas de escribir.

b. Prueba. Pruébala con peticiones reales. No con las frases ideales que tú escribirías sabiendo que existe la skill, sino con las frases vagas que usaría alguien que no sabe que existe:

"ayúdame con esto"
"qué pongo aquí"
"revisa este archivo"

Si la skill no se activa con esas frases, la description necesita trabajo. Prueba también los edge cases: inputs vacíos, formatos inesperados, peticiones a medias.

c. Revisión. Evalúa el output con estas preguntas:

• ¿El agente siguió los pasos del SKILL.md o se los saltó?
• ¿El output tiene el formato esperado?
• ¿Hay pasos ambiguos que el agente interpretó de forma distinta a lo previsto?
• ¿Se activó cuando no debía?
• ¿Dejó de activarse cuando debía?

d. Ajuste. En función de lo anterior:

• El agente no sigue los pasos > hacerlos más imperativos y explícitos.
• El output varía entre ejecuciones > especificar el formato exacto con un ejemplo.
• La skill no se activa > ampliar y hacer más agresiva la description.
• La skill se activa cuando no toca > añadir límites explícitos en la description.
• El SKILL.md es ambiguo > reescribir en imperativo directo, sin espacio para interpretación.

8. Errores comunes

Una skill puede fallar por mil razones. Algunos de los más habituales.

1. Description demasiado vaga. Si la description no es específica, el agente no activa la skill y todo lo demás da igual.

# Mal
description: Ayuda con código.

# Bien
description: >
  Usar cuando el usuario quiera revisar código en busca de
  valores hardcodeados. Activar si pega CSS, JS o cualquier
  archivo de estilos y pide revisión o limpieza.

2. Instrucciones ambiguas en el cuerpo. Si el cuerpo deja espacio para la interpretación, el agente tomará decisiones que no esperas.

# Mal
Puedes revisar el código y señalar problemas.

# Bien
Revisa el código en este orden exacto:
1. Primero detecta colores hardcodeados.
2. Luego espaciados.
3. Finalmente tipografía.

3. Meter todo en el SKILL.md. Un SKILL.md de 800 líneas es un problema: el agente lo carga entero en contexto aunque solo necesite una parte. Si crece demasiado, divide en archivos de referencia.

4. Scripts que no son idempotentes. Si el agente ejecuta un script dos veces por error y el resultado cambia, tienes un problema difícil de depurar. Los scripts deben producir siempre el mismo output para el mismo input.

5. Skills que se solapan. Dos skills con descriptions parecidas confunden al agente: puede activar la equivocada o no activar ninguna. Si tienes skills similares, los límites entre ellas deben ser explícitos en cada description.

6. Poner lógica de negocio en la description. La description es para el triggering, no para instrucciones. Si empiezas a meter reglas de comportamiento ahí, el agente puede ignorarlas.

# Mal
description: >
  Usar para commits. Seguir Conventional Commits.
  Nunca usar "fix" para features. Máximo 72 caracteres.

# Bien
description: >
  Usar para generar mensajes de commit.
# Las reglas van en el cuerpo

7. Asumir que el agente recuerda conversaciones anteriores. Una skill no tiene memoria entre sesiones. Todo el contexto necesario debe estar en el SKILL.md o en los archivos de referencia.

8. Una skill para todo. La tentación de hacer una skill muy genérica que cubra muchos casos es comprensible, pero cuanto más amplia la skill, más vaga tiene que ser la description y peor el triggering. Varias skills pequeñas y específicas funcionan mejor que una skill monolítica.

---

Una última nota antes de cerrar: una skill es código. No instales skills no testeadas de fuentes dudosas. Esto está evolucionando más rápido que nuestros equipos de seguridad, y solo un ejercicio de responsabilidad personal puede evitar problemas serios.

Referencias

• Especificación oficial: agentskills.io/specification
• Equipping agents for the real world with Agent Skills — Anthropic Engineering
• Effective context engineering for AI agents — Anthropic Engineering
• Documentación Claude Code skills
• Repositorio oficial de skills