Cómo crear buenos skills para tu agente de IA

Guía práctica para crear skills: paquetes de instrucciones reutilizables que le enseñan a tu agente a hacer una tarea bien, siempre. Si los prompts son el nivel 1, los skills son el nivel 2 — conviene leer antes Cómo escribir buenos prompts. Esta guía se basa en la práctica y en el curso oficial Introduction to Agent Skills de Anthropic Academy, en el que estoy certificado.

Idea central: si constantemente le enseñas lo mismo a un agente, ese conocimiento debería convertirse en un skill. Un prompt le dice a la IA qué hacer ahora; un skill le enseña cómo hacer algo bien — y queda guardado para siempre. Los skills son la memoria procedimental del agente: no almacenan lo que sabe, sino cómo hacer las cosas.

Parte 1 — Lo básico

¿Qué es un skill?

Un skill es una carpeta con un archivo SKILL.md (y opcionalmente plantillas, ejemplos y scripts) que empaqueta el conocimiento para una tarea específica: cómo generar tu informe semanal, cómo revisar código con tus estándares, cómo escribir posts con tu tono.

Lo importante: el agente lo carga solo cuando la tarea lo amerita. No ocupa espacio en cada conversación — está disponible, no presente.

Prompt vs. skill vs. herramienta

Los tres se confunden al principio. La diferencia:

Concepto	Qué es	Ejemplo
Prompt	Instrucciones para esta conversación	”Resume este documento en 5 viñetas”
Skill	Procedimiento reutilizable que se activa cuando la tarea calza	”Cómo se arma el informe mensual de este equipo”
Herramienta (tool)	Función ejecutable que el agente puede invocar	Buscar en la web, consultar una base de datos

Un skill puede contener prompts (instrucciones) y usar herramientas — es la capa que los organiza para una tarea concreta.

¿Cuándo crear un skill?

Tres señales claras:

1. Te repites. Ya escribiste las mismas instrucciones tres veces en conversaciones distintas → empaquétalas.
2. La tarea tiene pasos. Un procedimiento con orden, validaciones y formato de salida (generar un reporte, hacer un deploy, revisar un PR).
3. Hay conocimiento tuyo que el modelo no tiene. Tus estándares de código, el formato de tu empresa, el checklist de tu proceso — eso no está en ningún entrenamiento.

Si es una pregunta puntual de una vez, no necesitas skill: un buen prompt basta.

Parte 2 — La anatomía de un skill

La estructura de carpeta

mi-skill/
├── SKILL.md          ← obligatorio: instrucciones + metadata
├── plantilla.md      ← opcional: formatos de salida
├── ejemplos/         ← opcional: casos resueltos
└── scripts/          ← opcional: código que el agente ejecuta

El SKILL.md tiene dos partes

1) El frontmatter (metadata): lo primero del archivo, entre ---. Dos campos obligatorios:

---
name: informe-semanal
description: Genera el informe semanal de ventas en el formato
  corporativo. Úsalo cuando pidan "informe semanal", "reporte de
  ventas" o el cierre de la semana.
---

• name: identificador corto en minúsculas con guiones.
• description: la pieza más importante de todo el skill — ver la Regla 1.

2) El cuerpo: las instrucciones en Markdown — cuándo aplicarlo, los pasos, las reglas, los recursos disponibles.

Progressive disclosure: por qué los skills escalan

Este es el concepto clave que hace que los skills no saturen el contexto. La información se revela en tres niveles:

Resultado: puedes tener decenas de skills instalados y el agente solo “paga” el costo del que está usando. Es el mismo principio de darle la información correcta en el momento correcto que ya vimos en el harness.

Parte 3 — Las reglas de oro

Regla 1 — La descripción es el gatillo

El agente decide si activa tu skill leyendo solo la descripción. Si es vaga, el skill no se activa nunca (o se activa cuando no debe). Una buena descripción dice qué hace + cuándo usarlo, con las palabras que usaría la persona:

❌ “Skill para informes.”

✅ “Genera el informe semanal de ventas en formato corporativo con las cifras de la base de datos. Úsalo cuando pidan ‘informe semanal’, ‘reporte de ventas’ o el cierre de la semana.”

Regla 2 — Un skill, una habilidad

“Generar el informe de ventas” es un skill. “Todo lo relacionado con ventas” no es un skill, es una bodega. Si el SKILL.md empieza a cubrir tareas distintas, sepáralo.

Regla 3 — Instrucciones como checklist, no como ensayo

El cuerpo debe leerse como un procedimiento que otra persona (o el agente) puede seguir sin ti:

1. Lee los datos de la planilla de ventas. 2. Calcula el total por región y la variación contra la semana anterior. 3. Usa la estructura de plantilla.md — no inventes secciones. 4. Antes de entregar, verifica que los totales cuadren.

Regla 4 — No le enseñes lo que ya sabe

El modelo ya sabe qué es un promedio, cómo se escribe un email o qué es Python. El skill aporta lo específico tuyo: tu formato, tus reglas, tus excepciones, tus ejemplos. Todo lo demás es ruido que paga tokens.

Regla 5 — SKILL.md corto, detalle en anexos

Mantén el SKILL.md enfocado (idealmente bajo las 200-300 líneas). Si un paso necesita una referencia larga — la lista completa de códigos, el manual de estilo — ponla en un archivo anexo y referéncialo: “para el detalle de códigos, lee codigos.md”. Progressive disclosure en acción.

Regla 6 — Muestra ejemplos de resultado

Igual que en los prompts: un ejemplo de salida correcta enseña más que tres párrafos de reglas. Incluye en la carpeta uno o dos casos resueltos y apúntalos desde las instrucciones.

Regla 7 — Prueba la activación, no solo el contenido

Un skill tiene dos formas de fallar: hacer mal la tarea, o no activarse cuando debía (y activarse cuando no). Prueba con frases reales: ¿“hazme el reporte” lo dispara? ¿“resume este PDF” lo dispara por error? Ajusta la descripción hasta que ambas respuestas sean correctas.

Parte 4 — Técnicas intermedias

Limita las herramientas con allowed-tools

En el frontmatter puedes declarar qué herramientas puede usar el agente mientras ejecuta el skill. Un skill de solo lectura (analizar, revisar, resumir) no necesita permisos de escritura ni de ejecución — limitarlo es seguridad gratis.

Empaqueta scripts, no descripciones de scripts

Si un paso es determinístico — validar un RUT, convertir un formato, calcular fechas — incluye el script en la carpeta y ordena ejecutarlo, en vez de pedirle al modelo que “escriba código para…”. El script da siempre el mismo resultado; el código generado en el momento, no siempre.

Dónde viven los skills (en Claude Code)

• Del proyecto: .claude/skills/ dentro del repo — se comparten con todo el que clone el proyecto.
• Personales: en tu carpeta de usuario — te siguen a todos tus proyectos.
• De equipo/empresa: distribuidos como plugins o por la organización.

Además, todo skill se puede invocar explícitamente como slash command (/nombre-del-skill), sin esperar la activación automática. Los detalles de comandos están en el Glosario de comandos: Claude Code.

El mismo formato sirve en todo el ecosistema

Un skill bien escrito funciona en Claude Code, en claude.ai y en agentes construidos con la API de Anthropic — es un estándar, no una feature de una sola herramienta. Escríbelo una vez, úsalo donde trabajes.

Skills vs. CLAUDE.md vs. Hooks vs. Subagentes

En Claude Code hay cuatro mecanismos para “enseñarle” cosas al agente, y usar el equivocado produce arquitecturas difíciles de mantener. Cada uno cumple un propósito distinto:

Mecanismo	Qué es	Cuándo usarlo
CLAUDE.md	Contexto que se carga siempre, en cada sesión	Convenciones del proyecto, comandos de build, reglas generales que aplican a todo
Skill	Procedimiento que se carga cuando la tarea calza	Tareas específicas repetibles: generar un informe, revisar con tus estándares
Hook	Comando que se ejecuta automáticamente ante un evento	Reglas exigibles sin excepción: formatear al guardar, bloquear comandos peligrosos
Subagente	Agente aparte con su propio contexto e instrucciones	Trabajos paralelos o especializados que no deben contaminar la conversación principal

La pregunta clave: ¿esto aplica siempre (CLAUDE.md), a veces según la tarea (skill), debe cumplirse sí o sí sin depender del modelo (hook), o es un rol completo aparte (subagente)?

Parte 5 — Errores comunes (y cómo se ven)

Síntoma	Causa en el skill	Arreglo
Nunca se activa	Descripción vaga o sin las palabras del usuario	Regla 1: qué hace + cuándo + palabras gatillo
Se activa cuando no debe	Descripción demasiado amplia	Acota el “cuándo usarlo” y agrega qué NO cubre
Resultados inconsistentes	Instrucciones como prosa ambigua	Regla 3: checklist numerado con validaciones
Contexto saturado	Todo el detalle dentro del SKILL.md	Regla 5: mover referencias largas a anexos
Hace cosas de más	Sin límites de herramientas	allowed-tools + reglas explícitas de alcance
Le funciona solo al autor	Rutas absolutas, supuestos de tu máquina	Rutas relativas a la carpeta del skill, cero supuestos locales
Cálculos que a veces fallan	Le pide al modelo generar el código cada vez	Empaquetar el script y ordenar ejecutarlo

Parte 6 — Checklist antes de publicar tu skill

• ¿La descripción dice qué hace, cuándo usarlo y con qué palabras se pide?
• ¿Cubre una sola habilidad?
• ¿Las instrucciones son un checklist numerado que alguien más podría seguir?
• ¿Quitaste todo lo que el modelo ya sabe?
• ¿El SKILL.md es corto y el detalle vive en anexos?
• ¿Incluiste al menos un ejemplo de resultado correcto?
• ¿Lo determinístico va en scripts empaquetados?
• ¿Limitaste las herramientas al mínimo necesario?
• ¿Probaste que se activa con frases reales y no se activa con frases parecidas de otras tareas?
• ¿Funciona en una máquina que no es la tuya (sin rutas ni supuestos locales)?

Parte 7 — Plantilla lista para copiar

---
name: nombre-del-skill
description: [Qué hace, en una frase]. Úsalo cuando [situaciones
  concretas] o cuando pidan "[palabra gatillo 1]", "[palabra
  gatillo 2]".
---

# [Nombre de la habilidad]

## Cuándo usar este skill
- [Situación 1]
- [Situación 2]
- NO usar para: [tareas parecidas que no cubre]

## Pasos
1. [Primer paso, concreto y verificable]
2. [Segundo paso — si necesita referencia larga: "lee anexo.md"]
3. [Paso con validación: "verifica que X antes de continuar"]
4. [Entrega: usa la estructura de plantilla.md]

## Reglas
- NUNCA [lo que no se negocia — inventar datos, saltarse validaciones].
- SIEMPRE [formato, idioma, tono].
- Si falta información: [qué preguntar y a quién derivar].

## Recursos de esta carpeta
- plantilla.md — estructura de la salida
- ejemplos/caso-1.md — un resultado correcto de referencia
- scripts/validar.py — ejecutar para [validación determinística]

En una frase

Un buen skill empaqueta una sola habilidad: descripción que dispara con las palabras correctas, pasos como checklist, solo el conocimiento que el modelo no tiene, detalle en anexos, scripts para lo exacto y pruebas de que se activa cuando debe. Lo demás es iterar con casos reales.

---

Para seguir aprendiendo

• Cómo escribir buenos prompts — la base: las instrucciones que van dentro de cada skill
• Glosario de comandos: Claude Code — dónde viven los skills y cómo se invocan como slash commands
• Claude Code Workshop for Developers — el flujo completo donde los skills se usan en la práctica
• Certificado: Introduction to Agent Skills — mis notas del curso oficial de Anthropic Academy en que se basa parte de esta guía
• OpenClaw y Hermes: arquitectura de harnesses — Hermes lleva esta idea al extremo: un agente que escribe sus propios skills al resolver tareas (memoria procedimental automática)