Una Disección Técnica del Frontmatter de SKILL.md

Esta es una referencia técnica para el bloque de frontmatter dentro de un archivo SKILL.md de Claude. Su propósito es explicar cada campo y su efecto en el comportamiento de la habilidad, específicamente cómo se activa. La información aquí no es teórica; se basa en nuestra experiencia directa al analizar, instalar y probar 743 habilidades únicas enviadas a SkillProof. Nuestra metodología implica ejecutar cada habilidad contra un conjunto estandarizado de tareas de programación del mundo real, y una parte significativa de ese proceso es primero comprender la intención del autor tal como se declara en el SKILL.md.

Lo que hemos descubierto es que este pequeño bloque YAML es la parte más crítica y a menudo incomprendida de la definición de una habilidad. Un frontmatter mal configurado puede deshabilitar silenciosamente una habilidad, llevando a un autor a depurar su script cuando el problema está en los metadatos. Esta guía documenta lo que hace cada campo, cómo interactúan y qué configuraciones evitar.

El Bloque de Frontmatter de SKILL.md

Cada archivo SKILL.md comienza con un bloque de frontmatter YAML, delimitado por ---. Esta es una convención estándar en muchos generadores de sitios estáticos y herramientas de documentación, pero en el contexto de una habilidad de Claude, no es solo para consumo humano. El modelo analiza este bloque para comprender la identidad, capacidades y restricciones de la habilidad.

Esta claude skill yaml section es el panel de control de su habilidad. El modelo base utiliza estos datos para decidir si, cuándo y cómo ejecutar las herramientas que ha proporcionado. Pensar en ello como meros comentarios informativos es el primer error.

Un bloque de frontmatter mínimo se ve así:

---
name: example-skill
description: A brief but precise explanation of what this skill does.
allowed-tools: [python]
---

Examinaremos cada uno de estos campos, además de los indicadores críticos de control de invocación, basándonos en los patrones observados en los más de 700 archivos que hemos analizado.

Identidad Central: name y description

Estos dos campos definen lo que la habilidad es tanto para el usuario como para el modelo. Sin embargo, tienen roles muy diferentes en cómo se activa la habilidad.

name

El campo name es una cadena única que identifica la habilidad. Se utiliza para la invocación explícita cuando un usuario escribe @ seguido del nombre de la habilidad. Por ejemplo, @example-skill. El nombre debe ser una cadena única y sin espacios. Convencionalmente, está en minúsculas y utiliza kebab-case.

Aunque es importante para la identificación y las llamadas directas del usuario, el name tiene poca o ninguna influencia en la decisión autónoma del modelo de usar la habilidad. El modelo no infiere la capacidad del nombre git-history-analyzer. Se basa en la description para eso.

description

Este es el campo más importante de todo el frontmatter de SKILL.md. La description no es un comentario. Es el conjunto de instrucciones principal que le dice al modelo cuándo su habilidad es la herramienta adecuada para una tarea determinada. Es la documentación de la API para el propio modelo.

En nuestras pruebas, la calidad de la description es la variable con mayor correlación con la puntuación de éxito de una habilidad. Las descripciones vagas conducen a una activación inconsistente, un uso incorrecto de la herramienta o a que la habilidad sea ignorada por completo. Esta es una causa raíz frecuente cuando una habilidad de Claude no se activa como se espera.

Una description deficiente: "Analyzes code."

Esto es inútil. No proporciona información sobre qué tipo de análisis, qué entradas espera o qué salidas produce. El modelo no tiene ninguna razón para elegir esta habilidad sobre sus propias capacidades internas.

Una description funcional: "Accepts a file path as input. Reads the specified file and uses the py-complexity tool to calculate the cyclomatic complexity of each function. Returns a list of functions and their complexity scores."

Esto es efectivo porque es preciso y orientado a la acción:

1. Entradas: Establece claramente que acepta una ruta de archivo.
2. Acciones: Especifica lo que hace (lee el archivo, calcula la complejidad ciclomática).
3. Herramientas: Incluso sugiere la herramienta que utilizará (py-complexity).
4. Salidas: Define el formato de retorno esperado (una lista de funciones y sus puntuaciones de complejidad).

Cuando se le presenta al modelo una tarea como "Can you check the complexity of the functions in main.py?", puede hacer coincidir esta solicitud directamente con las capacidades descritas en la segunda description. La primera description sería ignorada.

Cuando escriba su propia habilidad de Claude, dedique la mayor parte de su tiempo a refinar la description. Escríbala como si estuviera documentando una función para que la use otro ingeniero, porque eso es exactamente lo que está haciendo.

Permisos de Herramientas: allowed-tools

El campo allowed-tools es una lista de ejecutables que la habilidad tiene permitido invocar. Esto actúa como un sandbox de seguridad. El modelo no puede, bajo ninguna circunstancia, llamar a una herramienta que no esté explícitamente listada en este array.

allowed-tools: [python, bash, jq]

Esta es una característica crítica de seguridad y fiabilidad. Evita que una habilidad ejecute código arbitrario y define claramente su alcance operativo. Durante nuestras pruebas, verificamos que las herramientas listadas sean apropiadas para el propósito declarado de la habilidad. Una habilidad que afirma ser un simple formateador JSON pero lista bash en allowed-tools es una señal de alerta. Si bien podría estar usando bash para canalizar a jq, también otorga a la habilidad la capacidad de ejecutar cualquier comando de shell, lo cual es una expansión innecesaria de privilegios.

Hemos visto habilidades fallar porque intentan llamar a una herramienta que no está listada. Por el contrario, hemos marcado habilidades por solicitar permisos demasiado amplios que no están justificados por su description o implementación. Se aplica el principio de mínimo privilegio: solo permita las herramientas exactas necesarias para que la habilidad funcione.

Control de Invocación: user-invocable y disable-model-invocation

Estos dos indicadores booleanos son menos comunes pero tienen un profundo impacto en el comportamiento de la habilidad. Controlan la fuente de la invocación: ¿puede un usuario llamar explícitamente a la habilidad y puede el modelo decidir usarla por sí mismo? El valor predeterminado para ambos es false si se omiten, pero el comportamiento predeterminado efectivo de una habilidad estándar asume user-invocable: true y disable-model-invocation: false.

Su interacción puede ser confusa, así que aquí hay una tabla resumen:

user-invocable	disable-model-invocation	Comportamiento	Veredicto de SkillProof
true (o omitido)	false (o omitido)	Estándar: El usuario puede mencionar con @; el modelo puede invocar de forma autónoma.	La configuración esperada para la mayoría de las habilidades.
false	false (o omitido)	Solo Autónomo: El usuario no puede mencionar con @; el modelo puede invocar.	Para tareas en segundo plano o funciones de ayuda.
true	true	Solo Explícito: El usuario debe mencionar con @; el modelo no puede invocar.	Para herramientas con efectos secundarios o alto costo.
false	true	Deshabilitado: Ni el usuario ni el modelo pueden invocar.	Configuración rota. Las marcamos.

user-invocable

Este indicador determina si un usuario puede activar directamente la habilidad usando una mención @. El valor predeterminado, true, es el comportamiento que la mayoría de los usuarios esperan. Una user-invocable claude skill es una que se puede llamar bajo demanda.

Establecer user-invocable: false significa que la habilidad solo puede ser activada por el proceso de toma de decisiones autónomo del modelo. El usuario no puede forzar su ejecución. Esta es una opción válida para habilidades que actúan como ayudantes en segundo plano o parte de una cadena de herramientas más grande, pero puede ser una fuente importante de confusión. Hemos probado varias habilidades donde este indicador se configuró como false sin ningún aviso en la documentación. Los usuarios que intentaban mencionar la habilidad con @ no veían respuesta y asumían que estaba rota. Si establece esto en false, debe documentarlo claramente.

disable-model-invocation

Este indicador es lo opuesto a user-invocable. Determina si el modelo tiene permitido elegir proactivamente la habilidad por sí mismo.

El valor predeterminado, false, permite que el modelo use la habilidad siempre que su description coincida con la solicitud del usuario.

Establecer disable-model-invocation: true prohíbe al modelo usar la habilidad de forma autónoma. La habilidad solo puede ejecutarse si user-invocable también es true y el usuario la menciona explícitamente con @. Esto es útil para herramientas que son costosas, tienen efectos secundarios significativos (como hacer una solicitud de red o modificar archivos), o requieren una entrada muy específica que el modelo podría no ser capaz de inferir correctamente por sí mismo.

La Combinación de Fallo Silencioso

La configuración más problemática que hemos descubierto en nuestras pruebas es la combinación de user-invocable: false y disable-model-invocation: true. Como muestra la tabla, una habilidad configurada de esta manera no puede ser activada por ningún medio. El usuario tiene bloqueada la capacidad de llamarla, y al modelo se le prohíbe elegirla.

En nuestra revisión de más de 700 archivos SKILL.md, hemos encontrado habilidades con esta configuración exacta. Desde la perspectiva del usuario, la habilidad está instalada pero es completamente no funcional. Es, en efecto, código muerto. En cada caso, ponemos estas habilidades en cola para una inspección manual. A veces es un error del autor. Otras veces, parece ser una forma de deshabilitar temporalmente una habilidad en un repositorio sin eliminarla. Independientemente de la razón, enviar una habilidad con esta configuración es un error.

Implicaciones Prácticas de 743 Pruebas de Habilidades

Comprender el frontmatter de la habilidad de Claude no es un ejercicio académico. Es la clave para construir habilidades fiables y efectivas. Nuestras pruebas de 743 habilidades han reforzado algunas verdades clave:

1. La description es el disparador. El tiempo dedicado a refinarla nunca es un desperdicio.
2. Los valores predeterminados suelen ser correctos. La mayoría de las habilidades deberían ser invocables por el usuario y por el modelo.
3. Las desviaciones deben ser deliberadas y documentadas. Si hace que una habilidad sea solo autónoma o solo explícita, sus usuarios necesitan saber por qué.

Por eso existe SkillProof. De las 743 habilidades que hemos procesado, 31 tuvieron un rendimiento peor que usar Claude directamente. Muchos de estos fallos no se debieron a un código deficiente, sino a un frontmatter SKILL.md mal construido que hizo que la habilidad se activara en el momento equivocado o no se activara en absoluto. Otras 204 habilidades pasaron nuestras pruebas pero requirieron una configuración no obvia, a menudo relacionada con la comprensión de cómo se configuraron los indicadores de invocación. Publicamos estos hallazgos —los éxitos y los fracasos— porque el verdadero valor de una habilidad se determina por su rendimiento en el mundo real, no solo por su código.

Encontrar habilidades que hagan esto correctamente es el propósito de nuestro directorio. Una habilidad bien configurada como un Codebase Summarizer tendrá una descripción precisa y configuraciones de invocación sensatas, lo que le permitirá funcionar como una extensión fiable del modelo.

Puede explorar las 508 habilidades que pasaron nuestras pruebas en nuestro catálogo. Cada listado incluye el frontmatter SKILL.md exacto utilizado y nuestro veredicto sobre su efectividad. Vea por sí mismo cómo es una habilidad bien configurada y probada en batalla.