Implementar soporte de skills en tu propio agente

Los once capítulos anteriores miraron el formato desde la óptica de quien escribe skills. Este lo mira desde la óptica opuesta: la de quien construye el agente que las descubre, las carga y las ejecuta. La documentación oficial dedica una sola página a este rol, How to add skills support to your agent, y cubre el ciclo completo: descubrir skills, informar al modelo sobre ellas, cargar su contenido en contexto y mantener ese contenido efectivo en el tiempo.

Lo normativo y lo que decides tú

Esa guía no es normativa. El documento autoritativo es la especificación, y solo define qué hay dentro de un skill; la política del repositorio lo dice explícitamente: la documentación explicativa, los ejemplos, los tests y las implementaciones no añaden requisitos al formato. Recordatorio del vocabulario que vimos en el capítulo de la especificación: DEBE (must), DEBERÍA (should) y PUEDE (may). La guía de clientes, en cambio, habla en términos de consider, optionally y most implementations: son prácticas, no obligaciones.

Lo fija la especificación	Lo decides tú, el implementador
Un skill es un directorio con, como mínimo, un SKILL.md	Dónde viven esos directorios
SKILL.md = frontmatter YAML + cuerpo Markdown	Qué ámbitos escaneas y con qué precedencia
Los seis campos del frontmatter y sus límites	Qué tan estricta es tu validación
Rutas relativas desde la raíz del skill	Formato y ubicación del catálogo
Divulgación progresiva en tres niveles	Mecanismo de activación
El cuerpo Markdown sin restricciones de formato	Si el modelo ve el frontmatter o solo el cuerpo
—	Permisos, confianza, filtrado, compactación, lenguajes ejecutables

La frase clave, literal de la guía: la especificación de Agent Skills no manda dónde viven los directorios de skills —solo define qué va dentro de ellos—, pero escanear .agents/skills/ significa que las skills instaladas por otros clientes conformes son automáticamente visibles para el tuyo, y viceversa.

El principio rector: divulgación progresiva

Nivel	Qué se carga	Cuándo	Coste en tokens
1. Catálogo	name + description	Al iniciar la sesión	~50-100 tokens por skill
2. Instrucciones	Cuerpo completo de SKILL.md	Al activarse el skill	<5000 tokens (recomendado)
3. Recursos	Scripts, referencias, assets	Cuando las instrucciones los referencian	Variable

El efecto declarado: un agente con 20 skills instaladas no paga el coste de 20 juegos completos de instrucciones por adelantado, solo el de las que realmente se usan. Si colapsas dos niveles —inyectando el cuerpo entero de cada skill en el system prompt— tendrás soporte funcional, pero habrás perdido justo la propiedad que hace útil el formato.

flowchart TD
    A["Etapa 1 · Descubrir<br/>escanear ámbitos de proyecto y usuario"] --> B["Etapa 2 · Parsear<br/>frontmatter YAML + cuerpo"]
    B --> C["Etapa 3 · Divulgar<br/>catálogo name + description"]
    C --> D{"¿La tarea coincide<br/>con alguna description?"}
    D -->|No| C
    D -->|Sí| E["Etapa 4 · Activar<br/>lectura de archivo o herramienta dedicada"]
    E --> F["Nivel 3 · Recursos bajo demanda"]
    F --> G["Etapa 5 · Gestionar contexto<br/>proteger de compactación y deduplicar"]
    G --> D

Etapa 1: descubrir skills

Al arrancar la sesión, encuentra todos los skills disponibles y carga sus metadatos.

Dónde escanear

La mayoría de los agentes locales escanean al menos dos ámbitos: proyecto (relativo al directorio de trabajo) y usuario (relativo al directorio personal). La guía nombra otros posibles: skills de organización desplegadas por un administrador, o skills empaquetadas con el propio agente.

Ámbito	Ruta	Propósito
Proyecto	<project>/.<tu-cliente>/skills/	Ubicación nativa de tu cliente
Proyecto	<project>/.agents/skills/	Interoperabilidad entre clientes
Usuario	~/.<tu-cliente>/skills/	Ubicación nativa de tu cliente
Usuario	~/.agents/skills/	Interoperabilidad entre clientes

Algunas implementaciones escanean además .claude/skills/, a nivel de proyecto y de usuario, por compatibilidad pragmática con las muchas skills ya instaladas ahí. Otras ubicaciones citadas: directorios ancestros hasta la raíz de git (monorepos), directorios de configuración XDG y rutas configuradas por el usuario. Todo esto es convención; ninguna de estas rutas está en la especificación.

Qué buscar

Dentro de cada directorio de skills, busca subdirectorios que contengan un archivo llamado exactamente SKILL.md:

~/.agents/skills/
- pdf-processing/
  - SKILL.md  # descubierto
  - scripts/
    - extract.py
- data-analysis/
  - SKILL.md  # descubierto
- README.md   # ignorado (no es un directorio de skill)

Reglas prácticas que recomienda la guía: saltar directorios que no contendrán skills como .git/ y node_modules/; opcionalmente respetar .gitignore; y poner límites razonables —por ejemplo profundidad máxima de 4-6 niveles y máximo 2000 directorios— para evitar escaneos descontrolados en árboles grandes.

MAX_DEPTH, MAX_DIRS = 6, 2000
SKIP = {".git", "node_modules", "dist", "build", ".venv"}

def discover(roots):
    """roots: lista de (scope, ruta), ordenada por precedencia ascendente."""
    vistos, encontrados = 0, []
    for scope, root in roots:
        for dirpath, dirnames, filenames in walk(root, max_depth=MAX_DEPTH):
            dirnames[:] = [d for d in dirnames if d not in SKIP]
            vistos += 1
            if vistos > MAX_DIRS:
                log.warning("límite de directorios alcanzado en %s", root)
                break
            if "SKILL.md" in filenames:
                encontrados.append((scope, join(dirpath, "SKILL.md")))
                dirnames[:] = []   # un skill no anida otros skills
    return encontrados

Colisiones, confianza y sandbox

Cuando dos skills comparten el mismo name, aplica una regla determinista. La convención universal entre las implementaciones existentes: los skills de proyecto sobrescriben a los de usuario. Dentro del mismo ámbito, first-found o last-found son igual de aceptables: elige uno y sé consistente. Registra un aviso ante cada colisión para que el usuario sepa que un skill quedó ensombrecido. Nada de esto está en la especificación.

Los skills de proyecto vienen del repositorio sobre el que se trabaja, que puede no ser de confianza —un proyecto open source recién clonado, por ejemplo—. La guía sugiere condicionar su carga a una comprobación de confianza, para que un repositorio desconocido no inyecte instrucciones en el contexto del agente en silencio.

flowchart LR
    A["Skill encontrado<br/>en ámbito de proyecto"] --> B{"¿Carpeta marcada<br/>como confiable?"}
    B -->|Sí| C["Cargar metadatos<br/>y publicar en el catálogo"]
    B -->|No| D["No cargar<br/>y registrar diagnóstico"]

Si tu agente corre en contenedor o servidor remoto no verá el sistema de archivos del usuario. Los skills de proyecto viajan con el repositorio clonado y se escanean igual; los de usuario y organización hay que aprovisionarlos desde fuera —clonando un repositorio de configuración, aceptando URLs o paquetes en los ajustes, o dejando subir directorios por una interfaz web—; y los integrados se empaquetan como assets estáticos del artefacto de despliegue. Una vez disponibles, el resto del ciclo es idéntico.

Etapa 2: parsear SKILL.md

Un SKILL.md tiene dos partes: frontmatter YAML entre delimitadores --- y un cuerpo Markdown después del cierre. El algoritmo son tres pasos: localizar el --- de apertura al inicio del archivo y el --- de cierre; parsear el YAML intermedio extrayendo name y description (requeridos) más los opcionales; y tomar todo lo posterior al cierre, recortado, como cuerpo.

Así lo implementa skills-ref, la librería de referencia del repositorio oficial —un artefacto de demostración, no un SDK de producción:

def parse_frontmatter(content: str) -> tuple[dict, str]:
    if not content.startswith("---"):
        raise ParseError("SKILL.md must start with YAML frontmatter (---)")

    parts = content.split("---", 2)
    if len(parts) < 3:
        raise ParseError("SKILL.md frontmatter not properly closed with ---")

    try:
        metadata = strictyaml.load(parts[1]).data
    except strictyaml.YAMLError as e:
        raise ParseError(f"Invalid YAML in frontmatter: {e}")

    if not isinstance(metadata, dict):
        raise ParseError("SKILL.md frontmatter must be a YAML mapping")

    return metadata, parts[2].strip()

Dos notas de fidelidad: content.split("---", 2) es un detalle de implementación, no un algoritmo de la spec; y skills-ref acepta también skill.md en minúsculas, tolerancia que la guía de clientes no comparte —ahí se pide un archivo llamado exactamente SKILL.md—.

YAML malformado

Los archivos escritos para otros clientes pueden contener YAML técnicamente inválido que sus parsers aceptan por casualidad. El caso más común son valores sin comillas con dos puntos:

# YAML técnicamente inválido: los dos puntos rompen el parseo
description: Use this skill when: the user asks about PDFs

La guía sugiere un fallback que entrecomille esos valores o los convierta a block scalars antes de reintentar. Mejora la compatibilidad entre clientes a coste mínimo.

Validación laxa

Aquí la guía se aparta a propósito de la especificación: avisa de los problemas, pero carga el skill igual cuando sea posible.

Situación	Acción recomendada
name no coincide con el directorio padre	Avisar y cargar igual
name supera 64 caracteres	Avisar y cargar igual
description ausente o vacía	Saltar el skill y registrar el error
YAML completamente imparseable	Saltar el skill y registrar el error

El criterio del corte: una description es imprescindible para la divulgación; sin ella el skill no puede aparecer en el catálogo y por tanto no puede activarse nunca. Guarda los diagnósticos para mostrárselos al usuario —comando de depuración, log o interfaz—, pero no bloquees la carga por problemas cosméticos.

Qué almacenar

Cada registro necesita al menos tres campos: name y description del frontmatter, y location, la ruta absoluta al archivo SKILL.md. Guárdalos en un mapa en memoria indexado por name para búsqueda rápida durante la activación. El directorio base del skill —el padre de location— se necesita después para resolver rutas relativas y enumerar recursos: derívalo de location cuando haga falta.

El cuerpo puedes guardarlo en el descubrimiento o leerlo desde location al activar. Guardarlo hace la activación más rápida; leerlo al activar usa menos memoria en agregado y recoge los cambios hechos al archivo entre activaciones. Ambas son válidas.

Etapa 3: divulgar el catálogo al modelo

Informa al modelo de qué skills existen sin cargar su contenido. Por cada skill incluye name, description y opcionalmente location, en el formato que le convenga a tu stack: XML, JSON o una lista con viñetas funcionan igual.

<available_skills>
  <skill>
    <name>pdf-processing</name>
    <description>Extract PDF text, fill forms, merge files. Use when handling PDFs.</description>
    <location>/home/user/.agents/skills/pdf-processing/SKILL.md</location>
  </skill>
</available_skills>

Este es el bloque que genera skills-ref to-prompt, y su propio docstring acota el alcance: es el formato que Anthropic usa y recomienda para los modelos Claude, y los clientes pueden formatear la información de otra manera según sus modelos o preferencias. No es obligatorio.

location cumple dos funciones: habilita la activación por lectura de archivo y le da al modelo una ruta base para resolver referencias relativas del cuerpo del skill, como scripts/evaluate.py. Si tu herramienta de activación devuelve el directorio del skill en su resultado, puedes omitirlo; si no, inclúyelo. Cada skill añade del orden de 50-100 tokens: incluso con decenas instaladas el catálogo sigue siendo compacto.

Dónde colocarlo y qué decir

Dos enfoques habituales, ambos válidos. La sección del system prompt es la opción más simple y funciona con cualquier modelo que tenga herramienta de lectura de archivos. La descripción de una herramienta dedicada de activación mantiene limpio el system prompt y acopla de forma natural descubrimiento y activación.

Junto al catálogo, un bloque corto de instrucciones de comportamiento. Si el modelo activa skills leyendo archivos:

The following skills provide specialized instructions for specific tasks.
When a task matches a skill's description, use your file-read tool to load
the SKILL.md at the listed location before proceeding.
When a skill references relative paths, resolve them against the skill's
directory (the parent of SKILL.md) and use absolute paths in tool calls.

Si activa mediante herramienta dedicada:

The following skills provide specialized instructions for specific tasks.
When a task matches a skill's description, call the activate_skill tool
with the skill's name to load its full instructions.

Mantenlas concisas: el objetivo es decir que los skills existen y cómo cargarlos; el detalle lo aporta el contenido una vez cargado.

Filtrado y catálogo vacío

Algunos skills deben quedar fuera: los deshabilitados por el usuario, aquellos a los que el sistema de permisos deniega acceso, y los que hayan optado por no ser invocados por el modelo —por ejemplo mediante un flag disable-model-invocation, que la guía menciona solo como ejemplo hipotético y no es un campo del formato—.

La regla es firme: oculta por completo los skills filtrados en vez de listarlos y bloquear al activar, para que el modelo no gaste turnos intentando cargar algo que no puede usar. Y si no se descubrió ningún skill, omite catálogo e instrucciones por completo: nada de un <available_skills/> vacío ni de registrar una herramienta sin opciones válidas, porque confunde al modelo.

Etapa 4: activar skills

La mayoría de las implementaciones se apoyan en el criterio del propio modelo como mecanismo de activación, en lugar de hacer matching de disparadores o detección de palabras clave del lado del harness.

flowchart TD
    A["El modelo lee el catálogo"] --> B{"¿Mecanismo<br/>de activación?"}
    B -->|Lectura de archivo| C["Llama a su herramienta de lectura<br/>con la location del catálogo"]
    B -->|Herramienta dedicada| D["Llama a activate_skill<br/>con el nombre del skill"]
    C --> E["Recibe el archivo completo<br/>incluido el frontmatter"]
    D --> F["El harness decide qué devolver:<br/>archivo completo o solo el cuerpo"]
    E --> G["Instrucciones en contexto"]
    F --> G
    G --> H["Recursos empaquetados<br/>cargados bajo demanda"]

Activación por lectura de archivo: el modelo llama a su herramienta estándar de lectura con la ruta del catálogo. No hace falta infraestructura especial y es lo más simple cuando el modelo tiene acceso a archivos.

Activación por herramienta dedicada: registras una herramienta —activate_skill, por ejemplo— que recibe un nombre y devuelve el contenido. Es obligatoria cuando el modelo no puede leer archivos, y opcional pero útil cuando sí puede. Ventajas que enumera la guía: controlar qué contenido se devuelve, envolverlo en etiquetas estructuradas, listar los recursos empaquetados, aplicar permisos o pedir consentimiento, y registrar la activación para analítica.

Si la usas, restringe el parámetro name al conjunto de nombres válidos, por ejemplo como enum, para que el modelo no alucine skills inexistentes. Y si no hay skills, no registres la herramienta.

{
  "name": "activate_skill",
  "description": "Load the full instructions for an available skill.",
  "input_schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string", "enum": ["pdf-processing", "data-analysis"] }
    },
    "required": ["name"]
  }
}

Activación explícita por el usuario

Los usuarios también deberían poder activar skills sin esperar al modelo. El patrón más común es un slash command o una sintaxis de mención (/skill-name, $skill-name) que el harness intercepta: el harness hace la búsqueda y la inyección, de modo que el modelo recibe el contenido sin ejecutar una acción de activación. Un autocompletado que liste los skills mientras el usuario escribe hace la función descubrible.

Qué recibe el modelo

Dos opciones, ambas documentadas como válidas. Con el archivo completo, el modelo ve el SKILL.md entero incluido el frontmatter; es el resultado natural de la lectura de archivo y una elección válida para una herramienta dedicada, y campos como compatibility pueden informar cómo ejecutar las instrucciones. Con solo el cuerpo, el harness parsea y quita el YAML; entre las implementaciones con herramienta de activación dedicada, la mayoría toma este camino. La guía cierra el punto sin escoger ganador: ambos funcionan en la práctica.

Envoltura estructurada y listado de recursos

<skill_content name="pdf-processing">
# PDF Processing

[cuerpo de SKILL.md]

Skill directory: /home/user/.agents/skills/pdf-processing
Relative paths in this skill are relative to the skill directory.

<skill_resources>
  <file>scripts/extract.py</file>
  <file>references/pdf-spec-summary.md</file>
</skill_resources>
</skill_content>

Tres beneficios: el modelo distingue las instrucciones del skill del resto de la conversación, el harness puede identificarlas durante la compactación, y los recursos quedan a la vista sin haberse cargado con avidez. Porque la herramienta puede enumerar los archivos de apoyo, pero no debe leerlos con avidez: el modelo carga archivos concretos bajo demanda cuando las instrucciones los referencian. Para directorios grandes, limita el listado y anota que puede estar incompleto.

Resolución de rutas relativas

La especificación pide referencias relativas desde la raíz del skill, a un nivel de profundidad desde SKILL.md. Del lado del cliente eso se traduce en una regla que la guía sugiere incluso pasar como instrucción al modelo: resuelve las rutas relativas contra el directorio del skill —el padre de SKILL.md— y usa rutas absolutas en las llamadas a herramientas.

def resolver(skill, ruta_relativa):
    base = Path(skill.location).parent          # directorio del skill
    destino = (base / ruta_relativa).resolve()
    if not destino.is_relative_to(base):        # evita salir del skill con ../
        raise PermissionError(f"ruta fuera del skill: {ruta_relativa}")
    return destino

Si tu agente tiene un sistema de permisos sobre archivos, incluye los directorios de skill en la allowlist para que leer los recursos empaquetados no dispare diálogos de confirmación. Sin eso, cada referencia a un script o a un archivo de referencia acaba en un diálogo y el flujo se rompe para cualquier skill que traiga algo más que su SKILL.md.

Ejecutar scripts con seguridad

La especificación es escueta con scripts/: contiene código ejecutable que los agentes pueden ejecutar, y los scripts deberían ser autocontenidos o documentar sus dependencias, incluir mensajes de error útiles y manejar los casos límite con elegancia. Añade que los lenguajes soportados dependen de la implementación del agente; las opciones comunes son Python, Bash y JavaScript. Qué se ejecuta y bajo qué condiciones lo defines tú.

• El entorno es no interactivo. La guía de scripts lo marca como un requisito duro del entorno de ejecución del agente: los agentes operan en shells no interactivos y un script que se bloquea esperando entrada quedará colgado indefinidamente. Imponlo desde el ejecutor —sin TTY, con timeout, con stdin cerrado—, no confíes en que el autor lo respete.
• El tamaño de salida es un recurso. Muchos harnesses truncan automáticamente la salida de herramientas más allá de un umbral; la guía cita del orden de 10-30K caracteres como ejemplo. Define el tuyo, aplícalo y documéntalo para quienes escriban skills.
• allowed-tools es experimental. Es una cadena separada por espacios de herramientas preaprobadas, y la propia spec advierte que el soporte puede variar entre implementaciones. Da un único ejemplo (Bash(git:*) Bash(jq:*) Read) sin definir gramática. Si lo soportas, documenta qué sintaxis interpretas; si no, ignóralo sin romper la carga del skill.
• La confianza se decide antes, no después. El punto de control natural es la etapa 1: un skill de proyecto no confiable no debería llegar ni al catálogo. Un skill que ya está en contexto es, a efectos prácticos, un conjunto de instrucciones que el modelo va a seguir.
• El allowlisting no es renuncia a los permisos. Permitir el directorio del skill evita diálogos por leer references/REFERENCE.md; no autoriza la ejecución arbitraria de scripts/* ni el acceso fuera del directorio. Trata lectura y ejecución como decisiones separadas.

Nada de esto lo exige el formato: la especificación no define firma, sandboxing ni modelo de permisos. La guía de clientes solo aporta consideraciones de confianza y allowlisting, redactadas como sugerencias.

Etapa 5: gestionar el contexto en el tiempo

Protege el contenido de skill de la compactación. Si tu agente trunca o resume mensajes antiguos cuando la ventana se llena, exime de la poda al contenido de skill. Las instrucciones de un skill son guía de comportamiento duradera: perderlas a media conversación degrada silenciosamente el rendimiento del agente sin ningún error visible —el modelo sigue operando, pero sin las instrucciones especializadas—. Dos enfoques: marcar las salidas de la herramienta de skill como protegidas, o usar las etiquetas estructuradas de la etapa 4 para identificarlas y preservarlas.

Deduplica activaciones. Lleva registro de qué skills se activaron en la sesión; si el modelo o el usuario intenta cargar uno que ya está en contexto, sáltate la reinyección.

Delegación a subagente (opcional). Patrón avanzado soportado solo por algunos clientes: en lugar de inyectar las instrucciones en la conversación principal, el skill se ejecuta en una sesión de subagente separada que hace la tarea y devuelve un resumen. Útil cuando el flujo es lo bastante complejo como para merecer una sesión dedicada.

Errores que debes manejar

Situación	Qué hacer
Subdirectorio sin SKILL.md	No es un skill: ignorarlo sin ruido
Frontmatter que no abre o no cierra con ---	Saltar el skill y registrar
YAML imparseable	Saltar el skill y registrar el error
Valor sin comillas con dos puntos	Reintentar entrecomillando o como block scalar
description ausente o vacía	Saltar: sin ella no puede divulgarse
name no coincide con el directorio	Avisar y cargar igual
name supera 64 caracteres	Avisar y cargar igual
Dos skills con el mismo name	Proyecto sobre usuario, avisar del ensombrecido
Árbol de directorios enorme	Cortar por profundidad y por número de directorios
Proyecto no confiable	No cargar skills de proyecto
El modelo pide un skill inexistente	Enum en el esquema; devolver error claro
Skill deshabilitado o sin permiso	Ocultarlo del catálogo, no bloquear al activar
Directorio con cientos de archivos	Limitar el listado y anotar que está incompleto
Script que espera entrada interactiva	Ejecutar sin TTY y con timeout
Salida de script desmesurada	Truncar según el umbral del harness
Activación repetida del mismo skill	Deduplicar
Compactación de contexto	Eximir el contenido de skill de la poda

Lista de verificación de conformidad

Descubrimiento

• Se escanea al menos un ámbito de proyecto y uno de usuario.
• Se escanea .agents/skills/ (proyecto y usuario) para interoperabilidad.
• El skill se detecta por un archivo llamado exactamente SKILL.md en un subdirectorio.
• Se omiten .git/, node_modules/ y similares.
• Hay límites de profundidad y de número de directorios.
• Las colisiones de name se resuelven con proyecto sobre usuario, de forma determinista.
• Se registra un aviso cuando un skill queda ensombrecido.
• Si aplica, los skills de proyecto se cargan solo bajo comprobación de confianza.

Parseo

• Se extraen name y description del frontmatter YAML.
• El cuerpo es todo lo posterior al --- de cierre, recortado.
• Se omite el skill si falta description o si el YAML es imparseable, con log.
• Se avisa, sin bloquear, si name no coincide con el directorio o excede 64 caracteres.
• Se conservan name, description y location (ruta absoluta).
• Los diagnósticos quedan disponibles para el usuario.

Divulgación

• El catálogo lleva name y description de cada skill.
• Se incluye location, salvo que la herramienta de activación devuelva el directorio.
• Hay un bloque conciso de instrucciones coherente con el mecanismo de activación.
• Los skills deshabilitados, sin permiso o con opt-out se ocultan del catálogo.
• Sin skills descubiertos no se emite catálogo, ni instrucciones, ni herramienta.

Activación

• El modelo puede activar un skill por su propio criterio.
• El usuario puede activarlo explícitamente por slash command o mención.
• Con herramienta dedicada, el parámetro de nombre está restringido, por ejemplo con enum.
• Los recursos empaquetados se listan, no se leen con avidez.
• Los directorios de skill están en la allowlist del sistema de permisos.
• Las rutas relativas se resuelven contra el directorio del skill y se pasan absolutas.

Gestión de contexto

• El contenido de skill queda exento de la poda por compactación.
• Las activaciones duplicadas se detectan y no se reinyectan.

Formato

• skills-ref validate ./my-skill pasa sobre los skills de referencia del cliente.

Probar tu implementación

La librería de referencia expone tres subcomandos útiles como banco de pruebas:

# Validar un skill contra las restricciones de la especificación
skills-ref validate path/to/skill

# Leer las propiedades del frontmatter como JSON
skills-ref read-properties path/to/skill

# Generar el bloque XML <available_skills> para el prompt del agente
skills-ref to-prompt path/to/skill-a path/to/skill-b

validate sale con código 0 si el skill es válido y 1 si hay errores. Úsalo como oráculo: si tu parser acepta algo que validate rechaza, has tomado una decisión de laxitud —legítima, pero consciente—; si rechaza algo que validate acepta, probablemente tengas un bug. Contrapeso: la propia librería declara que está pensada solo para demostración y no para producción. No la conviertas en dependencia de runtime.

Hacia dónde seguir

Con este capítulo cierras el recorrido completo: qué es el formato, cómo se escribe, cómo se prueba, cómo se distribuye, quién lo soporta y cómo se implementa. Tres caminos desde aquí.

Empaquetar skills para distribuirlas. Un skill suelto resuelve un problema; un paquete que agrupa varios skills y servidores MCP resuelve el flujo de trabajo de un equipo entero. Ese es el tema del curso hermano de Agent Plugins Spec.

Estudiar skills reales a escala. Leer más de cien skills escritas por un mismo equipo enseña patrones que ninguna guía formula: cómo se calibra el alcance, cómo se redactan las descriptions, cuándo se parte en references/. El catálogo oficial está desmenuzado en Google Skills.

Contribuir al estándar. El repositorio oficial acepta contribuciones bajo reglas explícitas:

• Discussions para propuestas, preguntas de diseño y feedback; Issues para bugs concretos en la spec, la documentación o la librería de referencia. Ante la duda, Discussions.
• Las propuestas deben abordar retos de implementación reales que hayas encontrado, no preocupaciones teóricas: muestra el problema y cómo tu propuesta lo resuelve.
• El listón para añadir a la spec es alto a propósito —es mucho más fácil añadir cosas a una especificación que quitarlas—; cada característica impone complejidad a todos los implementadores. Ante la duda, déjalo fuera.
• skills-ref no acepta contribuciones de código por ahora; sí bugs y feedback.
• No se aceptan envíos de skills: el proyecto no mantiene un directorio de skills de la comunidad, aunque podría cambiar.
• Si implementaste soporte de skills, puedes pedir figurar en el listado de clientes por pull request, con logos y una entrada en docs/snippets/clients.jsx. El requisito: que el producto esté públicamente disponible y sea capaz de descubrir y ejecutar skills hoy. No se listan productos que solo hayan anunciado la intención ni los que estén en beta privada.
• Toda asistencia de IA en una contribución debe declararse en el pull request o issue, indicando su alcance. Se exceptúan correcciones triviales de espaciado o erratas.
• Licencias: código y archivos de especificación bajo Apache 2.0; documentación bajo CC-BY 4.0.

El principio que gobierna el proyecto, literal de su AGENTS.md: Agent Skills es un formato pequeño, portátil y neutral respecto al cliente. Mantén el formato pequeño. El valor del estándar está en que cabe entero en la cabeza de quien lo implementa.

Resumen

• La guía de implementación para clientes no es normativa: la especificación define qué hay dentro de un skill, y ubicaciones, precedencias, permisos y formato del catálogo los decide cada cliente.
• El ciclo de vida tiene cinco etapas —descubrir, parsear, divulgar, activar y gestionar el contexto— y las tres primeras corresponden a los tres niveles de la divulgación progresiva.
• El descubrimiento busca subdirectorios con un archivo llamado exactamente SKILL.md; escanear .agents/skills/ es convención de interoperabilidad, no requisito.
• El parseo recomendado es laxo: avisar por name mal formado y cargar igual, saltar solo si falta description o el YAML es imparseable.
• El catálogo lleva name, description y opcionalmente location; los skills filtrados se ocultan por completo y sin skills no se emite catálogo alguno.
• La activación se apoya en el criterio del modelo, por lectura de archivo o por herramienta dedicada; conservar o eliminar el frontmatter funcionan igual en la práctica.
• Las rutas relativas se resuelven contra el directorio del skill y se convierten en absolutas antes de llamar a las herramientas.
• La ejecución de scripts la gobierna tu entorno: shells no interactivos, umbrales de truncado y permisos separados para leer y para ejecutar. El formato no define sandbox ni firma.
• El contenido de skill debe quedar exento de la poda por compactación: perderlo degrada al agente en silencio.
• skills-ref validate es el oráculo de conformidad del formato, pero es un artefacto de demostración, no un SDK de producción.