5 reglas para escribir el body de SKILL.md ocultas en la doc de Anthropic

Un Skill solo necesita dos líneas de YAML frontmatter para existir. Pero la forma en que escribes el body determina completamente la calidad del resultado.

Después de cruzar la documentación oficial de Anthropic y su blog de ingeniería, resumí los mecanismos de funcionamiento y los principios de escritura del body en cinco reglas. Todo empezó porque mis propios Skills fallaban de vez en cuando al cargar, y aproveché un fin de semana largo para verificar todo desde cero.

Si no entiendes el orden de ejecución de los Skills, el diseño del body se descarrila

Los Skills no se inyectan en la conversación como un prompt. Al iniciar, solo el name y la description se cargan en el prompt del sistema.

Cuando la solicitud del usuario coincide con la description, Claude usa la herramienta Bash para leer el SKILL.md completo. Solo entonces carga los archivos de referencia y los scripts conforme los necesita. El blog de ingeniería de Anthropic llama a esta estructura “revelación progresiva (progressive disclosure)”.

• Fase 1: Solo los metadatos (name + description) están siempre cargados. Unos 100 tokens por Skill.
• Fase 2: El body del SKILL.md entra a la ventana de contexto solo cuando hay coincidencia.
• Fase 3: Los archivos de las carpetas scripts y references se cargan en el momento de uso real.
• Al ejecutar scripts, el código en sí no entra al contexto, solo se consume la salida.

Sin entender esta estructura, vas a llenar el body de información innecesaria y te vas a saltar lo que realmente importa.

Escribir “cuándo usarlo” en el body desperdicia tokens

Mucha gente agrega una sección “When to Use This Skill” en el body. Después de crear mis propios Skills, descubrí que es completamente inútil. El body solo se lee después de que el Skill ya se activó.

“Cuándo usarlo” pertenece exclusivamente a la description. El repo oficial skill-creator de Anthropic lo deja bien claro.

• La description es el único mecanismo de activación (Claude no consulta contenido de “cuándo usar” en el body)
• Las descriptions tienen un límite de 1,024 caracteres. Escribir en tercera persona mejora la precisión de descubrimiento.
• El body debe contener reglas de la tarea, procedimientos y formatos de salida esperados.
• Elimina frases como “Usa este Skill cuando…” del body.

Mantén el body por debajo de 500 líneas y separa el resto

La primera línea de la guía de Anthropic dice que la ventana de contexto es un recurso compartido. Una vez cargado un Skill, comparte tokens con el historial de conversación y el prompt del sistema.

La recomendación oficial es mantener el body por debajo de 500 líneas y sacar el contenido detallado a archivos separados. El SKILL.md funciona como tabla de contenidos y los archivos de referencia como capítulos individuales.

• Body por debajo de 500 líneas recomendado (indicado en las best practices de Anthropic)
• Los archivos de referencia solo deben enlazarse a un nivel de profundidad desde el SKILL.md
• Con dos o más niveles de referencias anidadas, Claude puede leer solo las primeras 100 líneas con head -100
• Agrega una tabla de contenidos al inicio de cualquier archivo de referencia que pase de 100 líneas

Escribe asumiendo que Claude ya es inteligente

Explicar qué es un PDF en el body desperdicia tokens. Hay un principio que la guía de Anthropic enfatiza una y otra vez:

“No escribas lo que Claude ya sabe.”

Un ejemplo de código conciso de 50 tokens le gana a una explicación conceptual de 150 tokens. En mis pruebas con la misma tarea de extracción de PDF, el body conciso dio una precisión notablemente mejor que el verboso.

• Pregúntate en cada frase: “¿Esta explicación vale los tokens que cuesta?”
• Reemplaza las explicaciones conceptuales por ejemplos de código + formatos de salida esperados
• Clasifica la libertad de la tarea en tres niveles (alta/media/baja) para calibrar la intensidad de las instrucciones
• Pon libertad baja para tareas como migraciones de base de datos. Alta para revisiones de código.

Mete loops de verificación en el body para mejorar la calidad

Ejecutar → verificar → corregir → re-verificar. Este es el patrón de body más práctico que recomienda Anthropic. Meter checklists en el body reduce notablemente las veces que Claude se salta pasos.

La guía oficial también señala que un lenguaje fuerte como “MUST filter” logra mayor tasa de cumplimiento que “always filter”.

• Detalla los pasos en formato de checklist para tareas complejas
• Incluye loops de verificación de script → corrección de error → re-verificación en el body
• Usa “MUST” en lugar de “always”, la tasa de cumplimiento de Claude mejora
• Escribe mensajes de error específicos para que Claude pueda autocorregirse

Lo esencial

La description decide cuándo se activa un Skill. El body decide cómo se ejecuta. En el momento en que mezclas estos dos roles, el Skill ni se activa bien ni produce resultados de calidad.

Un buen Skill es como un buen documento de onboarding. Los documentos más poderosos parten de que el lector ya es inteligente.