5 reglas de escritura del body SKILL.md ocultas en la doc de Anthropic

Un Skill solo necesita dos líneas de YAML frontmatter para existir. Pero cómo escribas el body determina por completo la calidad del resultado.

Tras cruzar la documentación oficial de Anthropic y su blog de ingeniería, he destilado los mecanismos de funcionamiento y los principios de redacción del body en cinco reglas. Todo empezó porque mis propios Skills fallaban intermitentemente al cargar, y aproveché un fin de semana festivo para verificarlo todo desde cero.

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

Los Skills no se inyectan en la conversación como un prompt. Al arrancar, 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 según los necesita. El blog de ingeniería de Anthropic llama a esta estructura «divulgació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 en 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 en el contexto, solo se consume la salida.

Sin entender esta estructura, llenarás el body de información innecesaria y omitirás lo que realmente importa.

Escribir «cuándo usarlo» en el body desperdicia tokens

Mucha gente añade 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 ha activado.

«Cuándo usarlo» pertenece exclusivamente a la description. El repo oficial skill-creator de Anthropic lo deja explícito.

• 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 afirma 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 extraer el contenido detallado a archivos separados. El SKILL.md actúa como tabla de contenidos y los archivos de referencia sirven 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 mediante head -100
• Añade una tabla de contenidos al inicio de cualquier archivo de referencia que supere las 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 repetidamente:

«No escribas lo que Claude ya sabe.»

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

• Pregúntate en cada frase: «¿Esta explicación vale los tokens que cuesta?»
• Sustituye 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
• Establece libertad baja para tareas como migraciones de base de datos. Alta para revisiones de código.

Incorpora bucles 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. Incorporar listas de verificación en el body reduce visiblemente las probabilidades de que Claude se salte 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 lista de verificación para tareas complejas
• Incluye bucles 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 correctamente ni produce resultados de calidad.

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