Claude Skills: cómo diseñar un SKILL.md que no falla en producción
Esta guía explica la anatomía completa de un Claude Skill, los tres patrones más comunes por los que un SKILL.md rompe en producción, y cómo validar un skill antes de exportarlo a ~/.claude/skills/.
Por qué los SKILL.md fallan en producción
Tres formas en que un Claude Skill rompe sin que te des cuenta hasta que un usuario lo descubre:
Descriptions ambiguas
El campo description del frontmatter no diferencia bien. Claude no activa el skill cuando debería, o peor: lo activa para queries irrelevantes.
Reglas que se contradicen
Dos reglas del mismo skill se contradicen entre sí. Pasa desapercibido en review hasta que un usuario lo descubre en producción.
Crece y nadie sabe por qué
El SKILL.md llega a 500 líneas. Cada commit cambia algo, nadie recuerda qué razonamiento llevó a cada regla, ni cómo retroceder.
Diseñar el skill como grafo tipado
En lugar de escribir el SKILL.md a mano, modelas el skill como un grafo tipado: cada parte del skill (instrucciones, reglas, formato de salida, ejemplos, riesgos) es un nodo con un tipo, y las relaciones entre ellos —supports, mitigates, contradicts, requires— son explícitas y verificables.
Esto permite tres cosas que el markdown plano no permite:
- Validación semántica antes de exportar. El compilador detecta contradicciones explícitas, riesgos sin mitigar, ejemplos huérfanos y prerrequisitos rotos. No exporta si hay errores estructurales.
- Compilación determinista. El mismo grafo siempre produce el mismo
SKILL.md. Cada export se snapshotea con todo el grafo congelado, así puedes reproducir y revertir. - Trazabilidad. Cada regla, cada ejemplo, cada restricción tiene un origen explícito en el grafo. Sabes por qué está ahí.
Anatomía de un Claude Skill
Un skill bien estructurado tiene 8 nodos. Cada uno cumple un rol específico en el SKILL.md final:
1concept Skill Definition [SKILL]
2definition Frontmatter (Metadata) [META]
name, description y version. La description es el campo más crítico — Claude la usa para decidir cuándo activar el skill. Debe ser específica, máximo ~100 tokens, y diferenciable de otros skills.3role Main Instructions [INSTRUCTIONS]
4definition Rules & Constraints [RULES]
any incondicionalmente». Aquí es donde aparecen la mayoría de contradicciones cuando el skill crece.5style Output Format [OUTPUT]
6feature Examples (Few-shot) [EXAMPLES]
examples/ separada (ver siguiente nodo).7decision Create examples/ folder? [CONFIG]
examples/ dentro del paquete del skill, en vez de quedar inline en el SKILL.md. Útil para skills con muchos ejemplos largos.8future_direction Additional Resources [RESOURCES]
Flujo: de idea a skill instalable
- Modela tu skill como grafo. Carga el template Agent Skill Builder o parte de cero. Cada nodo tiene su tipo, contenido y relaciones explícitas con los demás.
- Validación semántica. Antes de exportar, el compilador revisa relaciones, detecta contradicciones entre reglas, avisa de riesgos sin mitigar y de ejemplos sin instrucción asociada.
- Exporta SKILL.md o ZIP. Descarga el paquete completo con frontmatter y carpeta
examples/. Listo para pegar en~/.claude/skills/.
Preguntas frecuentes
¿Qué es un Claude Skill?
SKILL.md y opcionalmente examples/) que extiende el comportamiento de Claude Desktop con instrucciones, reglas, formato de salida y ejemplos específicos para un dominio. Claude decide cuándo activarlo en función del campo description del frontmatter.¿Cómo se instala un skill en Claude Desktop?
~/.claude/skills/<nombre>/. Claude Desktop la detecta automáticamente al reiniciar. La carpeta debe contener al menos un archivo SKILL.md con frontmatter válido.¿En qué se diferencia un Claude Skill de un system prompt?
¿Por qué validar el grafo antes de exportar?
Empieza con un skill en 10 minutos
Carga el template Agent Skill Builder, llena los nodos, valida y exporta el SKILL.md.