📚 De dónde vienen las reglas
Las cifras de esta lección se verificaron en octubre de 2026 en la guía oficial Skill authoring best practices y en la documentación de skills, hooks y ventana de contexto de Claude Code. Las reglas básicas se han mantenido estables durante cerca de un año; lo que cambió fueron los modelos. Los ajustes para los modelos 5.5, al final, vienen de otra fuente y están identificados como tales.
Contenido detallado
📏 Tamaño y profundidad
O SKILL.md es un índice, no un manual. La guía oficial pide que el cuerpo
menos de 500 líneas; el resto va en archivos de referencia enlazados
directamente desde SKILL.md. Una referencia a la que solo se llega pasando por otra referencia está
anidada: el agente puede leer solo su vista previa (las primeras líneas, algo como un head -100)
y las reglas del final del archivo desaparecen sin aviso.
líneas es el límite del cuerpo del SKILL.md. Si lo supera, divídalo por tema en references/.
de profundidad: cada referencia está enlazada desde el propio SKILL.md, nunca solo desde otra referencia.
líneas o más en una referencia requieren un índice al inicio, para que incluso una lectura parcial muestre todo lo que abarca el archivo.
# Pricing reference
## Contents
- Base prices per plan
- Regional taxes
- Discounts and coupons <- at the end, but listed here
- Refund rules
## Base prices per plan
...💡 Consejo práctico
Abre el SKILL.md y cuenta cuántas referencias menciona. Toda referencia que aparece solo dentro de otra referencia es candidata a subir un nivel, con una línea «lee X cuando Y» en el SKILL.md.
🎚️ Grados de libertad
No todos los pasos merecen el mismo nivel de control. La guía los clasifica en grados de libertad: cuanto más frágil y costoso sea el error, menos margen debe tener el agente. Una misma skill suele combinar los tres. La prueba para cada paso es sencilla: «¿y si el agente hace este paso de otra manera?»
Instrucción en texto
Sirven varias respuestas y el contexto decide. Ej.: lluvia de ideas para títulos, revisión de código según el buen criterio.
Modelo con margen para variar
Hay un patrón preferido, pero se puede adaptar. Ej.: informe semanal con plantilla y parámetros.
Script exacto, sin parámetros sueltos
El error cuesta dinero, borra datos o publica algo. Ej.: factura, impuesto, migración de base de datos: "ejecuta exactamente este script".
💡 Consejo práctico
La imagen de la guía: un puente estrecho con un abismo a cada lado necesita barandilla (grado bajo); un campo abierto solo necesita una dirección (grado alto). Marca cada paso de tu skill con A, M o B antes de reescribirla.
🏷️ Descripción: tercera persona, «cuándo usar» y límites
La descripción se incorpora al prompt del sistema junto con las de todas las demás skills. Por eso la guía pide tercera persona («Procesa hojas de cálculo…», nunca «Yo puedo…» o «Tú puedes…»), lo que la skill hace y cuándo usarla, con las palabras que la persona escribe. Y hay límites de tamaño:
caracteres es el máximo del campo description en el frontmatter.
caracteres es donde Claude Code corta description + when_to_use sumadas en la lista de skills. Lo que exceda ese límite el modelo no lo ve.
✓ Tercera persona + cuándo
"Generates invoices and sends payment reminders. Use when the user asks to bill a client, issue an invoice or chase a late payment."
✗ Primera persona, sin activador
"I can help you with invoices."
💡 Consejo práctico
Lo mismo aplica al cuerpo: solo lo que el modelo no sabe. No expliques qué es una factura; guarda tus precios, términos y reglas internas. El contexto se comparte con la conversación, las otras skills y el historial.
✅ Checklist en la respuesta y bucle de verificación
Una tarea de muchos pasos necesita una checklist que el agente copia en la respuesta y va marcando, con una línea de retorno: «si el total no coincide, vuelve al paso 2». Y toda salida importante pasa por una bucle ejecutar → corregir → repetir hasta que la comprobación 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 cuenta.
Copy this checklist into your answer and tick each step:
- [ ] 1. Read the client data
- [ ] 2. Compute totals with scripts/total.py
- [ ] 3. Validate: python3 scripts/check_invoice.py out.json
- [ ] 4. Generate the PDF
If step 3 fails, fix the data and go back to step 2.
Only continue when validation passes.⚠️ Atención
«Revísalo bien antes de entregarlo» no es un loop. Un loop tiene un criterio que se cumple o falla y una instrucción sobre qué hacer si falla. Para trabajos largos, un verificador con contexto limpio, que no hizo el trabajo, suele encontrar más que la autocrítica.
🧪 Prueba en cada modelo
La misma skill se comporta de manera diferente en cada modelo. La guía oficial pide probarla en todos los modelos que la usarán y cita tres preguntas, una por familia: Haiku, Sonnet y Opus. La página no menciona Fable.
¿La skill orienta lo suficiente? Un modelo más pequeño necesita más detalle.
¿Es clara y concisa?
¿Evita explicar de más? Un modelo grande sufre con instrucciones redundantes.
💡 Consejo práctico
Prueba las skills de las que dependes, con tres solicitudes reales cada una. En las demás, el costo de la prueba no compensa.
📦 Paquetes, hooks y compactación
Tres reglas prácticas para que la skill funcione fuera de tu máquina y en una sesión larga:
Paquetes con la línea de instalación
No des por hecho que la biblioteca está instalada en la máquina de tu colega: enumera los paquetes exactos junto al comando de instalación, al lado del script que los necesita. En Claude API, la skill no instala nada; solo usa lo que ya está en el entorno.
Una regla que no puede incumplirse se convierte en un hook
Casi siempre se siguen las mayúsculas; el hook se sigue siempre. En Claude Code, el hook se puede declarar en el frontmatter de la propia skill: después de cargarla, se ejecuta antes de cada comando y permanece activo el resto de la sesión.
La compactación solo conserva el comienzo
Cuando se compacta la conversación, Claude Code conserva solo los primeros 5.000 tokens de cada skill cargada. Una regla crítica al final de un SKILL.md largo puede desaparecer después de la compactación: pon las más importantes al principio.
---
name: invoices
description: Generates invoices and sends payment reminders. Use when
the user asks to bill a client, issue an invoice or chase a late
payment. Not for accounting reports.
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/check-limit.sh"
---
# Invoices
Critical rules first: never send an invoice above the approval
limit without a human OK. (the hook enforces it)🆕 Ajustes para los modelos 5.5
Según la guía de prompting de Claude Fable 5 y Opus 5.5 citada por skill-creator-plus (RoboNuggets, MIT), las skills escritas para modelos antiguos tienden a demasiado prescriptivas y pueden empeorar el resultado. No es texto de la página de buenas prácticas de skills; considéralo orientación práctica y confírmalo en tu uso.
El paso a paso de lo que el modelo ya sabe y repetir el sentido común suelen ser peso muerto. Solo una ejecución con la línea y otra sin ella lo demuestran.
Los modelos 5.5 pueden rechazar la instrucción de "escribir el razonamiento paso a paso". Pide la respuesta, una explicación breve o el resumen de las acciones.
«Por debajo de 1.536 caracteres, porque Claude Code corta ahí» deja que el modelo resuelva el caso que la regla no previó.
Cuando todo grita, nada destaca. Una frase que oriente vale más que una lista de prohibiciones.
📋 Checklist para copiar
Pégala en una conversación con el agente junto con tu skill, o úsala tú antes de publicar.
Revisa esta skill según las reglas siguientes y marca cada elemento: - [ ] El cuerpo del SKILL.md tiene menos de 500 líneas - [ ] Cada referencia está enlazada directamente desde el SKILL.md, sin referencias anidadas - [ ] Toda referencia de más de 100 líneas comienza con un sumario - [ ] Cada paso tiene el grado de libertad adecuado: texto, modelo o script exacto - [ ] La descripción está en tercera persona y dice qué hace y cuándo usarla - [ ] La descripción tiene como máximo 1.024 caracteres y, junto con when_to_use, cabe en 1.536 - [ ] El cuerpo incluye solo lo que el modelo no sabe - [ ] Las tareas largas tienen una checklist que el agente copia en la respuesta, con una línea para volver - [ ] Existe un loop de ejecutar, corregir y repetir con un criterio que se cumple o falla - [ ] La skill se probó en cada modelo que la usará - [ ] Cada paquete que se use tiene al lado la línea de instalación - [ ] Las reglas que no se pueden infringir se convirtieron en hooks en el frontmatter de la skill - [ ] Las reglas críticas están al principio, dentro de los primeros 5.000 tokens - [ ] Ninguna instrucción pide escribir el razonamiento en la respuesta Por cada elemento que falle, indica dónde está el problema y propone la corrección antes de editar.
🔎 Audita tus skills con el validador
La parte mecánica de estas reglas se puede medir. El auditar-skills (proyecto INEMA, espejo del robonuggets/skill-creator-plus, licencia MIT) incluye un validador en Python puro, sin instalar nada ni llamar a una API, que lee la carpeta de skills y enumera errores y advertencias según cada regla. Guía: inematds.github.io/auditar-skills/guia.
git clone https://github.com/inematds/auditar-skills cp -r auditar-skills/skill-creator-plus ~/.claude/skills/ python3 ~/.claude/skills/skill-creator-plus/scripts/validate_skill.py --all ~/.claude/skills
📊 Ejemplo real
En una máquina de producción de INEMA, con la carpeta ~/.claude/skills llena de skills propias y de terceros, el validador se ejecutó en cerca de un segundo:
- ST5 · índice ausente en una referencia con más de 100 líneas: el mayor infractor, con 268 ocurrencias.
- DS3 · descripción sin "cuándo usar": 75 skills.
- ST4 · referencia anidada: 60 ocurrencias.
💡 Consejo práctico
Mide antes de reescribir. Empieza por las skills que más usas y por los errores más baratos de corregir: un resumen al principio y "cuándo usar" en la descripción resuelven la mayor parte de la lista.
✏️ Ejercicios prácticos
1. Ejecuta el validador
Ejecuta el comando anterior en tu carpeta de skills y anota las tres reglas que más se repiten. Compáralas con el ejemplo real de esta lección.
2. Marca los grados de libertad
Elige una skill tuya con más de cinco pasos y marca cada paso como alto, medio o bajo. ¿Algún paso de grado bajo está escrito como una instrucción suelta? Cámbialo por un script.
3. Pasa la checklist por una skill real ⭐
Pega la checklist que puedes copiar y tu skill en una conversación con Claude. Corrige los elementos que fallen, vuelve a ejecutar el validador y confirma que el número de errores disminuyó.
🎯 Resumen del módulo
Fin de la Ruta 1:
Ya entiendes la anatomía, la estructura, el activador y las reglas actuales. En la Trilha 2 analizarás una skill real de principio a fin y crearás la tuya.