Skills: enseñarle procesos a un agente de IA

¿Qué problema resuelven?

Un agente sin instrucciones especiales hace lo que puede con lo que sabe. Cuando una tarea tiene pasos propios (revisar un formulario según tu guía de accesibilidad, preparar un artículo con tu formato, desplegar en un orden fijo), esos pasos hay que enseñárselos.

Podrías escribirlos todos en el archivo de instrucciones permanentes, pero eso tiene un costo: cada sesión carga ese archivo completo, aunque la tarea no tenga nada que ver. Las skills resuelven esa tensión. El procedimiento vive en su propia carpeta y solo entra al contexto cuando hace falta.

Skills es además un formato abierto, creado por Anthropic y publicado como estándar en agentskills.io. Lo adoptan otras herramientas, como Cursor, Codex, Gemini CLI y GitHub Copilot. Una skill bien escrita no queda atada a un solo producto.

¿Cómo está escrita una skill?

Una skill es una carpeta. Lo único obligatorio es el archivo SKILL.md; puede incluir además scripts, referencias o plantillas:

revisar-contraste/
├── SKILL.md          # obligatorio: metadatos + instrucciones
└── referencias/
    └── wcag-resumen.md

El SKILL.md tiene dos partes. El frontmatter en YAML contiene el nombre y la descripción. El cuerpo, en Markdown, contiene el procedimiento:

---
name: revisar-contraste
description: Revisa el contraste de texto de una pantalla contra WCAG. Úsalo cuando el usuario pida revisar la accesibilidad de los colores.
---

Debajo del frontmatter van los pasos: qué leer, qué comprobar, cómo reportar. En Claude Code, todos los campos son opcionales, pero la documentación recomienda al menos description; el name por defecto es el de la carpeta y es lo que escribes para invocarla (/revisar-contraste).

Qué distingue una skill buena de una mediocre:

• Alcance pequeño. Un procedimiento, no una biblioteca entera.
• Descripción con verbos concretos. Dice qué hace y cuándo usarla, con el caso principal al inicio. En Claude Code, la descripción se recorta a 1.536 caracteres en el listado de skills, así que lo importante va primero.
• Entrada y salida claras. El cuerpo empieza por lo que necesita (qué archivo o qué pantalla) y termina con el formato del reporte.
• Criterio de parada. Indica cuándo debe preguntar en lugar de seguir adivinando.
• Probada con casos reales. Pruébala con dos o tres antes de compartirla.

Si el procedimiento es una tarea larga que no debe llenar tu conversación, Claude Code permite ejecutarla en un subagente con su propia ventana de contexto (context: fork). Ese subagente no ve tu conversación, así que la skill debe traer instrucciones explícitas.

¿Dónde vive y cómo se carga?

Según la documentación de Claude Code, una skill puede vivir en varios ámbitos. Los tres que más usarás:

Para un equipo, la ruta de proyecto es la más útil: la documentación recomienda subirla al repositorio para que todos la reciban, y la versión queda en git junto al código.

La carga es progresiva. La descripción de cada skill está en el contexto desde el inicio. El cuerpo se carga solo cuando la skill se invoca, y desde ese momento se queda en la conversación. Los archivos de apoyo, como una referencia larga, se leen únicamente si el SKILL.md indica cuándo hacerlo. La documentación recomienda mantener el archivo principal por debajo de 500 líneas y mover el detalle a archivos aparte.

¿Cuándo usar una skill y cuándo CLAUDE.md?

La documentación de Claude Code sugiere crear una skill cuando una sección de CLAUDE.md “has grown into a procedure rather than a fact” (se convirtió en un procedimiento y dejó de ser un hecho). En la guía de memoria añade que un procedimiento de varios pasos se mueve a una skill. En la práctica:

Si pones un procedimiento en CLAUDE.md, lo pagas en cada sesión. Si lo pones en una skill, lo pagas solo cuando lo usas.

Una skill no conviene en estos casos:

• La instrucción es un hecho corto. Un párrafo en CLAUDE.md basta.
• El procedimiento cambia tanto que la skill queda vieja en una semana. Ese criterio se revisa a mano.
• La acción tiene efectos secundarios y no hay paso de aprobación. Para publicar o desplegar, usa disable-model-invocation: true y que solo tú la lances.

¿Por qué le importa a un diseñador?

Porque las skills convierten un criterio de diseño en un proceso repetible, y forman parte del context engineering: decidir qué entra al contexto y cuándo. Una persona que sabe cómo revisa una pantalla puede escribirlo como procedimiento, y el equipo entero usa la misma revisión. Algunas tareas de diseño que caben bien en una skill:

• Un checklist de revisión de pantallas con sus criterios de “listo”.
• Un procedimiento para redactar microcopy siguiendo la guía de tono.
• Un flujo para convertir una entrevista en hallazgos con evidencia.

Ejemplo

Ejemplo ilustrativo: un equipo tiene un CLAUDE.md de 300 líneas con reglas de accesibilidad, de tono y un procedimiento de revisión de pantallas. El agente ignora parte de las reglas porque el archivo está saturado. El equipo mueve la revisión a una skill llamada revisar-pantalla, con una descripción clara y un checklist de cinco puntos. El CLAUDE.md baja a las reglas que siempre aplican. Cuando alguien pide revisar una pantalla, el agente carga la skill y sigue el checklist completo; el resto del tiempo, ese texto no ocupa contexto.

Un cuerpo mínimo para esa skill podría verse así:

## Entrada
Una pantalla (archivo o captura) y el flujo al que pertenece.

## Pasos
1. Lista los textos y colores usados.
2. Revisa contraste, tamaño de texto y estados de foco.
3. Reporta cada hallazgo con: dónde está, por qué importa y cómo corregirlo.

## Si falta información
Pregunta qué componente es antes de proponer cambios.

Errores comunes

• Escribir una descripción vaga como “ayuda con diseño”. El agente no sabe cuándo usarla.
• Poner procedimientos enormes en el cuerpo sin archivos de apoyo.
• Duplicar la misma regla en la skill y en CLAUDE.md, y dejar que se contradigan. Mantén una sola fuente para cada regla.
• Dejar que el agente lance por su cuenta una skill con efectos secundarios, como desplegar.
• Crear skills para cada tarea de una vez. Empieza con las que el equipo repite.

Fuentes

• Extend Claude with skills, documentación de Claude Code
• How Claude remembers your project, documentación de Claude Code
• Create custom subagents, documentación de Claude Code
• Agent Skills: formato abierto, agentskills.io