📋 Una skill es el POP de tu agente
¿Eres nuevo aquí? POP es la sigla de «procedimiento operativo estándar»: el paso a paso escrito que una empresa usa para garantizar que una tarea se haga siempre de la misma manera, sin importar quién la realice. Un skill es exactamente eso, pero para tu agente: un archivo de texto reutilizable que enseña en detalle cómo realizar un proceso específico, desde «cómo escribir una publicación con el estilo de mi empresa» hasta «cómo generar un informe financiero siguiendo estas reglas».
La diferencia con lo que ya viste en la Trilha 2 es el disparador. Una herramienta MCP (módulo 2.1) la elige el agente
en el momento, según lo que esté disponible. Una skill la carga cuando reconoce la tarea — ya sea porque
escribiste un comando explícito (tipo /relatorio-financeiro),
ya sea porque tu frase en lenguaje natural coincide con la descripción que la skill hace de sí misma.
Nadie tiene que escribir ningún comando: solo describir lo que quiere.
💡 Concepto principal
Skill = markdown reutilizable, que se carga cuando el agente reconoce la tarea y se activa mediante un comando o lenguaje natural.
- •Un empleado nuevo no tiene tus años de experiencia — pero puede consultar el manual plastificado del escritorio.
- •La skill es ese manual: se escribe una vez y se consulta cada vez que se repite la tarea.
🔍 Por dentro
Tú también tienes SOP mentales que nunca escribiste: «cuando el cliente se queja del plazo, primero confirmo la fecha y después ofrezco dos opciones». La skill te obliga a escribirlo una vez, y el agente empieza a seguir ese mismo procedimiento cada vez, sin olvidar ningún paso.
📁 La carpeta por dentro
Físicamente, una skill es una carpeta con el nombre de la skill.
Dentro de ella, un archivo obligatorio llamado skill.md,
y dos tipos de contenido opcional: una carpeta references/
con documentos más largos y una carpeta scripts/
con pequeños programas que la skill puede ejecutar.
Leyenda: el único archivo obligatorio es el skill.md en la parte superior de la carpeta; references/ e scripts/ existen, pero solo se abren cuando el paso a paso lo indica; ese es el tema del módulo 3.2.
🏷️ El front matter: la etiqueta de la skill
¿Eres nuevo aquí? Front matter es
un encabezado de metadatos en la parte superior de un archivo Markdown, delimitado por tres guiones (---)
arriba y abajo. Piensa en ello como la etiqueta pegada en el lomo de una carpeta de archivo físico: antes de
abrirla y leer todo el contenido, ya sabes de qué se trata con solo mirar la etiqueta.
El front matter de una skill necesita al menos dos campos: name (el
nombre corto de la skill) y description (una
frase que dice qué hace la skill y cuándo usarla). Eso es todo lo que el agente lee todo el tiempo; el cuerpo del archivo
solo se abre cuando la skill se activa. Esto se explica con más detalle en el módulo 3.2.
---
name: relatorio-financeiro
description: Gera o relatório financeiro mensal no padrão da empresa,
a partir de uma planilha exportada do sistema de vendas. Use quando
o usuário pedir "relatório financeiro", "fechamento do mês" ou
"resumo de vendas".
---
# Relatório financeiro mensal
## Passo a passo
1. Peça o caminho da planilha exportada se não foi informado.
2. Leia as colunas: data, valor, categoria.
3. Some por categoria e calcule o total do mês.
4. Gere o arquivo `relatorio-<mês>.md` seguindo o modelo em
`references/modelo-relatorio.md`.
5. Mostre o resumo em texto antes de salvar o arquivo.💡 Consejo práctico
Escribe la description pensando en cómo TÚ pedirías la tarea en voz alta, no en términos técnicos. Esa es la frase que el agente compara con tu pedido para decidir si esa skill sirve. El módulo 3.4 trata por completo sobre eso.
📝 El cuerpo: el paso a paso de verdad
Después del front matter, el resto del skill.md es
Markdown normal: el mismo formato de texto de CLAUDE.md (módulo 0.4). Aquí está el proceso en sí: los
pasos numerados, las reglas que debes seguir, los ejemplos y las advertencias sobre lo que no hacer. Piensa en esto como el
núcleo del manual plastificado: la etiqueta de la portada te indicó el tema; ahora las páginas interiores enseñan
el procedimiento completo.
✓ Anatomía bien hecha
- ✓Pasos numerados, uno por línea, en orden de ejecución
- ✓Detalle extenso (tabla de códigos, ejemplos largos) desplazado a
references/ - ✓Indica explícitamente cuándo NO usar la skill
✗ Anatomía mal hecha
- ✗Un párrafo corrido, sin pasos claros
- ✗Pega todo en el
skill.md— incluso la tabla enorme que solo se usa una vez cada diez ejecuciones - ✗Da por sentado que el agente «va a adivinar» cuando algo no está escrito
🔍 Por dentro
No hay un límite estricto de tamaño, pero lo que funciona en la práctica es mantener el cuerpo breve: entre un párrafo de contexto y una lista de pasos; por lo general, quepa en una página. Si el tema requiere mucho más detalle, eso indica que parte debería convertirse en un archivo en references/, y no recargar el cuerpo principal.
📚 Referencias y scripts: los apéndices
La carpeta references/ guarda
documentos más extensos —una tabla de categorías, un glosario de términos internos, un ejemplo detallado—
que el agente solo abre si las instrucciones indican explícitamente que lo haga («si necesitas el detalle X, lee el archivo Y»).
Es el apéndice técnico del manual: existe, está ahí, pero nadie lo lleva en la cabeza todo el tiempo.
La carpeta scripts/ guarda
pequeños programas —un script de Python que calcula un total, un script de shell que renombra archivos en lote—
que la skill puede ejecutar en vez de pedirle al agente que reinvente toda esa lógica desde cero cada vez. Se ejecuta más
rápido y siempre da el mismo resultado, porque es código determinista, no una decisión nueva del modelo en cada ejecución.
🎯 Concepto principal
- •
references/= conocimiento bajo demanda (el agente lee texto) - •
scripts/= acción bajo demanda (el agente ejecuta código) - •Ninguna de las dos afecta el día a día: solo entran en acción cuando se las llama
💡 Consejo práctico
Regla práctica para decidir dónde va algo: si vuelves a leer ese fragmento cada vez que ejecutas la skill, va en el cuerpo de skill.md. Si solo consultas de vez en cuando («¿cuál era el código de la categoría X?»), va a references/.
⏱️ Qué sucede cuando se invoca la skill
Juntando todo: cuando pides algo en lenguaje natural o escribes el comando, el agente recorre una pequeña secuencia de decisiones hasta que la skill se convierte en acción. Mira la línea de tiempo de una llamada real.
Pides: «cierra el informe financiero del mes»
Frase normal, sin comando especial.
El agente compara tu frase con la description de cada skill instalada
Reconoce la correspondencia con la description de la skill relatorio-financeiro.
Carga todo el cuerpo del skill.md de esa skill
Ahora sí, lee el paso a paso completo —no solo la etiqueta.
Sigue los pasos; abre references/ o ejecuta scripts/ solo si el paso lo indica
En este ejemplo: lee el modelo de informe en references/ en el paso 4.
⚠️ Atención
Si dos skills tienen descriptions demasiado parecidas, el agente puede elegir la equivocada o dudar. El módulo 3.4 muestra cómo escribir activadores que no entren en conflicto.
Verificación rápida (opcional): ¿cuál es el único archivo obligatorio dentro de la carpeta de una skill?