Skills
Las skills son la capa de conocimiento de los agentes: archivos de instrucciones que se cargan solo cuando hacen falta, sin inflar el contexto. Vemos cómo funcionan por dentro, cómo escribir descriptions que realmente disparen, y los errores más comunes que hacen que una skill falle en silencio.
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 medioResponderá 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:
LOLEl 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, iconosEl ú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
/nombrecomo 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.docx7. 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 cuerpo7. 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.
9. Pero, ¿realmente sirven las skills?
«Descubre las 13 mejores skills de Claude Code para crear interfaces UI/UX profesionales», dicen en una web; «10 Python Skills That Will Make You Unstoppable in 2025», anuncian en otra; «I Tried 100 Claude Skills. These Are The Best», cuentan en un post en Medium. Sobre todo en lo que que atañe al ciclo de desarrollo de software, en internet hay una montonera de expresiones acerca de las capacidades de determinadas skills: que si con frontend-design ya no necesitamos saber nada de diseño, que si gracias a postgresql-skill los modelos saben trabajar con SQL; que si con changelog-generator, los agentes pueden llevar la bitácora de un proyecto. Son todas definitivas, la quintaesencia de la eficacia, unstoppables. Pero, ¿esto es realmente así? ¿De verdad los modelos consiguen realizar determinadas tareas genéricas mejor gracias a este tipo de skills?
En marzo de 2026, Tingxu Han et al. publicaron un paper, SWE-Skills-Bench: Do Agent Skills Actually Help in Real-World Software Engineering? en el que recogían los resultados de una investigación sobre el impacto real de las skills en el desarrollo de software y las conclusiones indicaban que la mayor parte no aportaba prácticamente nada.
En síntesis, vieron que:
- El 80% de las skills testadas no producían ninguna mejora.
- La ganancia media era solo del +1,2%.
- Algunas skills especializadas sí que eran muy útiles.
- Curiosamente, algunas skills empeoraron el rendimiento.
- El impacto general dependía en gran medida del contexto, del dominio y de cómo estaba diseñada la skill.
En otras palabras, el trabajo cuestiona la idea tan extendida de que basta con incorporar skills como si no hubiera un mañana para que los agentes programen mejor. Los modelos punteros ya saben programar muy bien y darles más indicaciones genéricas solo sirve para aumentar el coste en tokens y, en el peor de los casos, despistarlos. Ahora bien, ¿sucede lo mismo con las skills sobre cuestiones específicas?
En SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks, un paper de marzo de 2026, Xiangyi Li et al. publicaron los resultados de una investigación que abarcaba más materias además del desarrollo. Vamos a ver algunos detalles interesantes del estudio.
En un marco de trabajo que denominaron SKILLSBENCH, analizaron 84 tareas distribuidas en 11 dominios.
| Dominio | Nº tareas |
|---|---|
| Ingeniería de Software | 16 |
| Oficina y trabajo administrativo | 14 |
| Ciencias naturales | 12 |
| Producción de contenido | 11 |
| Ciberseguridad | 8 |
| Finanzas | 8 |
| Robótica | 5 |
| Manufactura | 3 |
| Energía | 3 |
| Matemáticas | 2 |
| Salud | 2 |
Además, definieron tareas con diferentes grados de dificultad para evitar que el benchmark estuviera compuesto únicamente por tareas triviales.
- 17 tareas core, que son las que un humano tardaría menos de una hora en realizar.
- 47 tareas extended, que llevarían a un humano entre 1 y 4 horas.
- 26 tareas extreme, más de 4 horas.
Trabajaron con tres agentes: —Claude Code de Anthropic; Codex CLI de OpenAI y Gemini CLI de Google— y varios modelos punteros: GPT-5.2 (OpenAI), Claude Opus 4.5, Claude Opus 4.6, Claude Sonnet 4.5, Claude Haiku 4.5 (Anthropic), Gemini 3 Pro, y Gemini 3 Flash (Google). Todos con temperatura 0 y adaptados al harness correspondiente. Es decir, en Claude Code sus modelos y así. Desconozco porqué dejaron fuera del experimento los modelos chinos. Sospecho que habría sido interesante incorporar al menos DeepSeek y Qween, así como algún nanomodelo potente, como Gemma.
Por último, indicar que pasaron cada tarea a los diferentes pares de agentes - modelos tres veces:
- Una sin skills. Solo la tarea a resolver.
- Otra con todas las skills asociadas, que podían incluir instrucciones, ejemplos, recursos, fragmentos de código, etcétera.
- Y una tercera, muy interesante, con skills autogeneradas para comprobar si el propio modelo podía producir autoinstrucciones útiles.
Sacaron 4 grandes hallazgos del estudio:
- Las skills solo ayudan en determinados casos, la mejora depende mucho del modelo, del agente y de la materia trabajada. En promedio, atendiendo a un score propio del estudio: sin skills: 24,3%; con skills: 40,6%.
- Las skills autogeneradas no ayudan. El resultado en estos casos fue incluso negativo, lo que indica que los modelos no pueden producir de forma fiable el conocimiento procedimental que sí saben aprovechar cuando alguien lo ha escrito previamente.
- Menos es más. Las Skills pequeñas y enfocadas funcionan mejor que la documentación exhaustiva.
- Las skills pueden sustituir parcialmente al tamaño del modelo. Un modelo pequeño equipado con buenas skills puede competir con modelos más grandes en tareas procedimentales.
En síntesis, las skills sí funcionan, pero no porque añadan más información, sino porque aportan procedimientos concretos y reutilizables. Cuanto más especializadas, concisas y alineadas con la tarea estén, mayor es su impacto. Cuando son largas, genéricas o redundantes, dejan de ayudar e incluso pueden perjudicar.
Y aquí está la clave para montar un buen sistema de skills: que sean de calidad y específicas.
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. En caso de duda, siempre puedes utilizar alguna herramienta para comprobar la seguridad de las skills, como skillspector de Nvidia.
