Agent Skills

Divulgación progresiva

Tres niveles, los mismos tres que describe la especificación:

• El catálogo. En cada turno, el prompt del agente lleva un menú de las habilidades que parecen pertinentes: título, descripción de una línea, slug. Nunca el cuerpo. Tres por turno por defecto, seis como máximo.
• La activación. El agente llama a la herramienta load_playbook con un slug para leer los pasos completos. El argumento slug queda ligado, turno a turno, a un enum con exactamente los slugs de ese menú: un nombre inventado se rechaza antes del despacho en lugar de costarle al agente una vuelta entera. Cuando no hay menú, la herramienta ni siquiera se registra.
• Los recursos. Todavía no. Aquí una habilidad es un único SKILL.md; scripts/, references/ y assets/ adjuntos se leen y se ignoran, en vez de soportarse a medias.

Una vez cargada, una habilidad sigue cargada. Las ejecuciones comprimen los resultados de herramienta más antiguos para contener el coste, y las habilidades activadas quedan exentas: sus instrucciones sobreviven literales durante el resto de la ejecución, por larga que se haga. Una habilidad que se desvanece en silencio a mitad de tarea es peor que una que nunca se cargó.

Qué habilidades llegan al menú

Dos pasadas. Las palabras clave de los disparadores coinciden con el turno como subcadenas sin distinguir mayúsculas; luego una pasada semántica completa la lista a partir de un embedding del título, la descripción, los disparadores y el comienzo del cuerpo de cada habilidad, admitida solo por encima de un umbral de similitud calibrado. Una habilidad sin disparadores está siempre activa y siempre se ofrece. Qué activar lo decide el modelo: aquí nada le impone una habilidad.

Meter una habilidad

• La biblioteca. Paquetes curados, instalables en un agente con un clic. Es la superficie de descubrimiento que usa casi todo el mundo.
• Escribir una. Título, descripción, palabras clave y los pasos, en la pestaña Playbooks del agente.
• La API. POST /api/agents/:id/playbooks/import acepta { files: [{ name, content }] } e importa cada archivo de forma independiente: un archivo malo falla solo y los demás entran igual. Cada archivo pasa un escaneo de seguridad antes de que se guarde nada, y una importación nunca sobrescribe una habilidad existente: una colisión de slug vuelve como omitida.
• Sacar una de un documento. POST /api/agents/:id/playbooks/generate acepta { artifactId } — un documento que ya está en el espacio de trabajo — o { content, sourceName }, y saca de él un procedimiento: cuándo aplica, los pasos, las reglas de decisión, el vocabulario. No es la tubería de subida, que convierte un documento en pasajes que se consultan; esto lo convierte en algo que el agente hace. El procedimiento se escribe de cero, nunca se extrae: la fuente puede ser el manual con derechos de otro, y una habilidad que lo cite sería una copia. Los documentos largos se leen desde el principio hasta un límite, y la respuesta dice cuándo se cortó. El resultado llega desactivado: nadie escribió esas palabras, así que una persona lee el borrador y lo enciende, o nunca se ejecuta.

En la interfaz no hay botón de subida, a propósito. Un SKILL.md se convierte en instrucción permanente para un agente que tiene en la mano las herramientas de un espacio de trabajo: un archivo subido sin más es un vector de inyección de prompts, no una comodidad. La ruta de API de arriba, solo para el propietario, es la excepción deliberada.

Sacar una habilidad

Cualquier habilidad se exporta como un zip que contiene <nombre>/SKILL.md — la forma de directorio que describe la especificación, no un archivo suelto. Descomprímelo en ~/.agents/skills/ o .claude/skills/ y se carga en ese cliente sin renombrar nada, y skills-ref validate pasa tal cual. Quien llame a la API y quiera el archivo desnudo puede pedir text/markdown.

El frontmatter lleva name y description. Nuestras extensiones — palabras clave, orden y una marca de procedencia — viajan bajo metadata, porque el validador de referencia de la especificación rechaza las claves de primer nivel desconocidas y una exportación nuestra nunca debería ser el archivo que lo haga fallar.

Qué nos negamos a honrar

• allowed-tools se descarta, siempre. La especificación lo define como herramientas que preaprobar para una habilidad, que es justo lo que no hay que aceptar de un archivo que llega por API o dentro de un paquete compartido: dejaría que el contenido importado se ampliara solo los permisos. Qué herramientas puede llamar un agente es una propiedad de su rol, nunca de un archivo que ha leído.
• compatibility se descarta por una razón más aburrida: describe el entorno para el que se escribió la habilidad, que no dice nada del nuestro.
• Todo lo que quede fuera del frontmatter documentado se ignora en vez de adivinarse. El parser acepta la forma pequeña y fija que define la especificación, y nada exótico.

Límites

Treinta habilidades por agente, 64 kB por archivo importado y un cuerpo con tope: una habilidad que ya no cabe en ese presupuesto son dos habilidades. Los nombres son letras minúsculas, dígitos y guiones simples: la especificación permite más, pero aquí el nombre también es una URL.

En otra parte

La especificación es la autoridad sobre el formato. Para la API HTTP con la que los agentes actúan en la red, consulta la documentación de la API.