Una skill es un índice, no un manual. Le enseña al agente a hacerlo a tu manera, siempre igual.

Descripción + cuerpo

A descripción (en tercera persona: «crea facturas y envía recordatorios») es lo que el agente lee para decidir si usa la skill. El cuerpo incluye las reglas más importantes al principio, los pasos y los enlaces al resto. Breve: solo lo que el modelo no puede deducir por sí solo.

Detalles bajo demanda

Precios, términos, formatos, ejemplos de entrada y salida: un archivo por tema, todos enlazados directamente desde SKILL.md. Los archivos largos empiezan con un índice, para que incluso una lectura parcial muestre todo lo que abarcan.

Lo que no puede variar

Cuando un error cuesta dinero, borra datos o publica algo, el paso se convierte en un script exacto. Cuando una regla debe aplicarse en cada ejecución, sale del texto y se convierte en un hook, que Claude Code ejecuta automáticamente, se use o no la skill.

SKILL.md breve, un nivel de profundidad

Cuerpo de menos de 500 líneas; el resto, en archivos enlazados directamente desde SKILL.md. Los archivos a los que solo se llega a través de otro archivo pueden recibir una vista previa (las primeras líneas), y las reglas del final desaparecen.

Índice al principio de los archivos largos

Las referencias de más de 100 líneas empiezan con una lista de su contenido. Así, aunque solo lea el principio, el agente sabe que «descuentos» está al final y va directamente a esa sección.

Grado de libertad según el riesgo

Alto: instrucción sencilla (lluvia de ideas). Medio: modelo con variaciones (informe semanal). Bajo: script exacto (factura, impuesto, migración). Una skill combina los tres; la prueba es: «¿y si el agente hace este paso de otra manera?».

Prueba en cada modelo que vayas a usar

Haiku: ¿la skill guía lo suficiente? Sonnet: ¿es clara y concisa? Opus y Fable: ¿evita explicar de más? Prueba las skills de las que dependes; las demás no compensan el costo.

Solo lo que el modelo no sabe

El contexto es un bien público. No expliques qué es una factura; guarda tus precios, términos y reglas internas. Descripción en tercera persona, con las palabras que escribe la persona.

Lista de verificación con una línea para «volver»

Las tareas de muchos pasos necesitan una lista que el agente copie en la respuesta y vaya marcando; cada paso debe incluir «se considera listo cuando…» y una línea del tipo «si el total no coincide, vuelve al paso 2».

Ciclo de verificación

Ejecutar, corregir lo que falló y repetir hasta que pase. La comprobación no tiene que ser código: comparar el borrador con la guía de estilo y enumerar cada desviación también sirve. Para trabajos largos, un verificador con contexto limpio supera la autocrítica.

Patrones para definir la salida

Una plantilla que indique cuánta rigidez requiere; dos o tres pares de entrada y salida cuando importa el estilo; un flujo condicional cuando hay bifurcaciones. Un patrón y una salida de emergencia, nunca un menú de cinco opciones.

Diseñada para compartir

No des por sentado que la biblioteca está instalada en el equipo de tus colegas: enumera los paquetes exactos y pon la línea de instalación junto al script que los necesita. La Claude API no instala nada.

Las reglas que no pueden romperse se convierten en hooks

«Nunca envíes una factura superior a R$ 50 mil sin aprobación», escrito en mayúsculas, se cumple casi siempre. Un hook se cumple siempre: se declara en el frontmatter de la skill, se ejecuta antes de cada comando y sigue activo durante el resto de la sesión.

Prueba antes de borrar

Los pasos a paso de lo que el modelo ya sabe, las listas largas de comportamientos y el sentido común repetido suelen ser peso muerto. Solo una ejecución con la línea y otra sin ella lo demuestra.

Pide la respuesta

La instrucción de «escribir el razonamiento paso a paso» puede ser rechazada por los modelos 5.5. Pide la respuesta, una explicación breve o el resumen de las acciones.

Regla con un porqué

«Por debajo de 1.536 caracteres, porque Claude Code corta el listado ahí» permite que el modelo se ocupe del caso que la regla no previó y le indica al próximo editor cuándo la regla dejó de ser relevante.

Usa mayúsculas solo para las reglas estrictas

«Empieza por el resultado, después el detalle» funciona tan bien como enumerar cada comportamiento no deseado. Cuando todo grita, nada destaca.

Di cómo y cuándo se verifica

Para ejecuciones largas o de riesgo, un subagente que no hizo el trabajo lo verifica frente a la especificación. Es el mismo método del área Execução Longa.

Una carpeta en ~/.claude/skills

git clone https://github.com/inematds/auditar-skills && cp -r auditar-skills/skill-creator-plus ~/.claude/skills/

En Codex, la misma carpeta en ~/.agents/skills. En claude.ai, comprime SKILL.md, references/ y scripts/ en un archivo ZIP.

Todas las skills a la vez

python3 ~/.claude/skills/skill-creator-plus/scripts/validate_skill.py --all ~/.claude/skills

Una tabla por skill: errores, avisos y las reglas incumplidas (FM, DS, ST, CT, WF, SC, NM, HK, TS, LB). --json para procesar.

AUDIT · NEW · REFINE

«Audita mi skill de deploy» genera el informe, primero los fallos, con archivo y línea. «Convierte esto en una skill» redacta tres prompts de prueba antes de crear la carpeta. «La skill olvida el filtro de fecha, corrígelo» reescribe la regla en torno al motivo; por lo general, queda más corta.

skill-creator (Claude Code)

Viene con Claude Code: crea, mide y optimiza la descripción de una skill, con evaluaciones y comparación de variantes. Es el punto de partida; /skill-doctor señala las skills sin uso.

writing-skills (Superpowers)

La skill del kit Superpowers para escribir y probar skills con TDD de documentación: línea base sin skill, escenario de presión y, después, la skill. Se aborda en el curso Superpowers de INEMA.

Skills For Real Engineers (Matt Pocock)

Los nombres de los modos de fallo (no-op, duplicación, sedimento, dispersión, conclusión prematura) vienen de aquí. Curso de INEMA más abajo.