Anatomía de un skill: SKILL.md y estructura de carpetas

En el capítulo anterior vimos qué problema resuelven las Agent Skills. Ahora abrimos la caja: qué archivos componen un skill, qué contiene cada uno y en qué orden los lee el agente.

La especificación es deliberadamente pequeña. Dice literalmente:

A skill is a directory containing, at minimum, a SKILL.md file

Eso es todo lo obligatorio. Un directorio y un archivo. El resto son convenciones de organización que la propia especificación etiqueta como recomendaciones.

Nota sobre el lenguaje normativo

A lo largo del curso traduzco el lenguaje de la especificación con precisión:

• DEBE (must): requisito. Si no se cumple, el skill es inválido según el formato.
• DEBERÍA (should): recomendación fuerte. Se puede incumplir con motivo.
• PUEDE (may): permiso explícito. Nada obliga a usarlo.

La especificación de Agent Skills no declara adherencia a RFC 2119 ni usa mayúsculas: escribe must, should y may en minúscula. Aun así, la distinción es real y la respeto en todo el texto. Cuando algo sea consejo de una guía de autoría y no del formato, lo digo explícitamente.

El mínimo viable

Un skill válido puede ser esto y nada más:

roll-dice/
- SKILL.md

Con este contenido, literal del quickstart oficial:

---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.
---

To roll a die, use the following command that generates a random number from 1
to the given number of sides:

```bash
echo $((RANDOM % <sides> + 1))
```

```powershell
Get-Random -Minimum 1 -Maximum (<sides> + 1)
```

Replace `<sides>` with the number of sides on the die (e.g., 6 for a standard
die, 20 for a d20).

La documentación lo resume así: “That’s it — one file, under 20 lines.”

No hay archivo de manifiesto, ni package.json, ni instalador, ni registro donde inscribirse. La unidad de distribución es la carpeta.

El árbol canónico

Este árbol aparece idéntico en specification, en la página de overview y en el README del repositorio del estándar:

skill-name/
- SKILL.md     # Required: metadata + instructions
- scripts/     # Optional: executable code
- references/  # Optional: documentation
- assets/      # Optional: templates, resources
- ...          # Any additional files or directories

La cláusula que acompaña a los directorios opcionales es la parte que más se malinterpreta:

A skill directory may contain any files and directories beyond the required SKILL.md. The conventions below are recommendations for organizing common types of content.

Es decir: scripts/, references/ y assets/ no son nombres reservados ni obligatorios. Son las tres carpetas que la especificación sugiere porque cubren los tres tipos de contenido más comunes. Puedes añadir evals/, templates/, data/, un LICENSE.txt o lo que tu skill necesite.

El archivo SKILL.md

La regla normativa es una sola frase:

The SKILL.md file must contain YAML frontmatter followed by Markdown content.

Dos partes, separadas por delimitadores ---. La guía para implementadores de clientes lo describe con el mismo corte: “a SKILL.md file has two parts: YAML frontmatter between --- delimiters, and a markdown body after the closing delimiter.”

flowchart TD
    A["SKILL.md"] --> B["Frontmatter YAML<br/>entre delimitadores de tres guiones"]
    A --> C["Cuerpo Markdown<br/>tras el delimitador de cierre"]
    B --> B1["name · obligatorio"]
    B --> B2["description · obligatorio"]
    B --> B3["license · compatibility<br/>metadata · allowed-tools<br/>opcionales"]
    C --> C1["Instrucciones libres<br/>sin restricciones de formato"]

El frontmatter: seis campos, ni uno más

La especificación define exactamente seis campos. No hay más. Cualquier otro que veas por ahí es una extensión de un cliente concreto o una invención.

Campo	¿Obligatorio?	Restricciones
name	Sí	Máximo 64 caracteres. Solo minúsculas, números y guiones. No DEBE empezar ni terminar con guion.
description	Sí	Máximo 1024 caracteres. No vacío. Describe qué hace el skill y cuándo usarlo.
license	No	Nombre de la licencia o referencia a un archivo de licencia empaquetado.
compatibility	No	Máximo 500 caracteres. Indica requisitos de entorno: producto previsto, paquetes de sistema, acceso a red, etc.
metadata	No	Mapeo clave-valor arbitrario, de claves string a valores string.
allowed-tools	No	Cadena separada por espacios con herramientas preaprobadas que el skill PUEDE usar. Experimental.

Un detalle que conviene fijar desde ya: el límite de description es de 1024 caracteres, no de 1024 tokens. Es un límite duro del formato, verificable con len().

El frontmatter mínimo, literal de la especificación:

---
name: skill-name
description: A description of what this skill does and when to use it.
---

Y un ejemplo con campos opcionales, también literal:

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

Fíjate en dónde vive version: dentro de metadata, no como campo de primer nivel. No existe un campo version en el formato. Tampoco author, tags, category, icon ni triggers. Si necesitas guardar algo así, metadata es el lugar previsto: “clients can use this to store additional properties not defined by the Agent Skills spec”. La recomendación que acompaña: usar nombres de clave razonablemente únicos para evitar colisiones accidentales.

Sobre compatibility, la especificación añade una nota que ahorra frontmatter innecesario: “Most skills do not need the compatibility field.” Solo DEBERÍA incluirse si el skill tiene requisitos de entorno específicos. Ejemplos literales:

compatibility: Designed for Claude Code (or similar products)
compatibility: Requires git, docker, jq, and access to the internet
compatibility: Requires Python 3.14+ and uv

allowed-tools merece una advertencia doble. Primero, es una cadena separada por espacios, no una lista YAML. Segundo, está marcado como experimental: “Support for this field may vary between agent implementations”. El único ejemplo que da la especificación es allowed-tools: Bash(git:*) Bash(jq:*) Read, sin definir gramática alguna para esa sintaxis.

El cuerpo Markdown

Aquí la especificación es sorprendentemente permisiva:

The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively.

Las secciones recomendadas son tres:

• Instrucciones paso a paso.
• Ejemplos de entradas y salidas.
• Casos límite comunes.

Y un aviso de coste que condiciona todo el diseño del skill:

Note that the agent will load this entire file once it’s decided to activate a skill. Consider splitting longer SKILL.md content into referenced files.

Traducido a decisión práctica: cada línea que escribes en SKILL.md la paga el agente en contexto cada vez que activa el skill, incluso si esa línea no aplica a la tarea concreta. Por eso la recomendación de mantenerlo bajo 500 líneas y bajo 5000 tokens. Ambas son recomendaciones, no requisitos: los únicos límites duros del formato son los 64, 1024 y 500 caracteres de name, description y compatibility.

Cómo escribir bien ese cuerpo es el tema del capítulo 5.

La relación entre name y el nombre del directorio

Esta es la regla estructural que más errores causa. El campo name:

• DEBE tener entre 1 y 64 caracteres.
• Solo PUEDE contener caracteres alfanuméricos en minúscula y guiones.
• No DEBE empezar ni terminar con guion.
• No DEBE contener guiones consecutivos.
• DEBE coincidir con el nombre del directorio padre.

Los ejemplos inválidos son literales de la especificación, con su comentario original:

name: PDF-Processing  # uppercase not allowed
name: -pdf            # cannot start with hyphen
name: pdf--processing # consecutive hyphens not allowed

La consecuencia de la última regla: si renombras la carpeta, tienes que renombrar el campo, y viceversa. Son un par acoplado.

flowchart LR
    D["Directorio<br/>pdf-processing/"] -->|debe coincidir| N["frontmatter<br/>name: pdf-processing"]
    N -->|debe coincidir| D
    D --> F["pdf-processing/SKILL.md"]

¿Por qué el estándar exige esta redundancia? Porque el descubrimiento es por sistema de archivos. La guía para implementadores describe el criterio: buscar dentro de cada directorio de skills “subdirectories containing a file named exactly SKILL.md”. El nombre de la carpeta es lo que un humano ve en el árbol y lo que aparece en una URL de repositorio; el campo name es lo que el agente ve en su catálogo. Si divergen, el humano y el agente están hablando de cosas distintas.

Hay un matiz sobre caracteres no ASCII que conviene conocer y no resolver a la ligera. El texto de la especificación es ambiguo: la tabla dice “Lowercase letters, numbers, and hyphens only”, mientras la viñeta dice “May only contain unicode lowercase alphanumeric characters (a-z, 0-9)” — menciona Unicode y a la vez acota a a-z y 0-9. La librería de referencia skills-ref implementa la lectura amplia, con normalización NFKC y un comentario que dice “Skill names support i18n characters (Unicode letters) plus hyphens”. Eso es comportamiento de una implementación de demostración, no una aclaración normativa. En la práctica: si quieres portabilidad máxima, quédate en a-z0-9-.

Los directorios opcionales, uno por uno

scripts/

Contains executable code that agents can run.

Los scripts DEBERÍAN, según la especificación:

• Ser autocontenidos o documentar claramente sus dependencias.
• Incluir mensajes de error útiles.
• Manejar los casos límite con elegancia.

Y una frase que evita expectativas equivocadas: “Supported languages depend on the agent implementation. Common options include Python, Bash, and JavaScript.” El formato no obliga a ningún lenguaje ni garantiza que un runtime concreto esté disponible. Si tu skill necesita uv o deno, ese es el caso de uso del campo compatibility.

Ojo con otra expectativa: el agente no ejecuta los scripts automáticamente. La especificación dice “code that agents can run”. Es el modelo quien decide ejecutarlos siguiendo las instrucciones de tu SKILL.md. Si no los mencionas en el cuerpo, es probable que nunca se ejecuten.

Todo el detalle de scripts —dependencias inline, diseño para uso agéntico, salidas estructuradas— está en el capítulo 7.

references/

Contains additional documentation that agents can read when needed.

Los ejemplos que da la especificación:

• REFERENCE.md — referencia técnica detallada.
• FORMS.md — plantillas de formularios o formatos de datos estructurados.
• Archivos de dominio: finance.md, legal.md, etc.

Son ejemplos, no nombres requeridos. La regla de diseño que sí importa:

Keep individual reference files focused. Agents load these on demand, so smaller files mean less use of context.

Un archivo de referencia de 3000 líneas que mezcla cinco temas anula el beneficio: el agente lo carga entero para consultar un párrafo.

assets/

Contains static resources.

Tres categorías nombradas:

• Plantillas: de documento, de configuración.
• Imágenes: diagramas, ejemplos.
• Archivos de datos: tablas de consulta, esquemas.

La diferencia práctica con references/ es el destinatario. Lo de references/ está escrito para que el agente lo lea y entienda. Lo de assets/ está pensado para que el agente lo use o copie: una plantilla .docx, un schema.json, un CSV de códigos.

Cualquier otro archivo

La línea - ... del árbol canónico es literal. Puedes poner un README.md para humanos, un LICENSE.txt referenciado desde el campo license, o un directorio evals/ con casos de prueba —la convención evals/evals.json viene de la guía de evaluación, que veremos en el capítulo 9, y no forma parte del formato.

flowchart TD
    Q{"¿Qué tipo de<br/>contenido es?"}
    Q -->|"Código que el agente ejecuta"| S["scripts/"]
    Q -->|"Documentación que el agente lee"| R["references/"]
    Q -->|"Plantillas, datos, imágenes que el agente usa"| A["assets/"]
    Q -->|"Instrucciones que se necesitan siempre"| K["cuerpo de SKILL.md"]
    Q -->|"Cualquier otra cosa"| O["archivo o directorio libre"]

Rutas relativas: cómo se enlazan las piezas

La regla normativa cabe en una línea:

When referencing other files in your skill, use relative paths from the skill root

El ejemplo literal de la especificación:

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py

Nada de rutas absolutas. La guía Using scripts lo refuerza: “Use relative paths from the skill directory root to reference bundled files. The agent resolves these paths automatically — no absolute paths needed.” Y añade que la misma convención vale dentro de los archivos de apoyo: las rutas de ejecución escritas en references/*.md también son relativas a la raíz del skill, porque el agente ejecuta los comandos desde ahí.

Del lado del cliente, la guía para implementadores describe el mecanismo: el directorio base del skill —el padre del SKILL.md— es lo que se usa para resolver rutas relativas y enumerar los recursos empaquetados, y la instrucción sugerida al modelo es “resolve them against the skill’s directory (the parent of SKILL.md) and use absolute paths in tool calls”.

Hay además un límite de profundidad recomendado:

Keep file references one level deep from SKILL.md. Avoid deeply nested reference chains.

Es decir: SKILL.md referencia references/api.md; references/api.md no DEBERÍA referenciar references/api-errores.md, que a su vez referencia otro. Cada salto es una decisión más que el agente puede no tomar.

Ejemplo 1: un skill mínimo, comentado

Estructura:

convenciones-commit/
- SKILL.md

Contenido de SKILL.md:

---
name: convenciones-commit
description: Redacta mensajes de commit siguiendo la convención del repositorio. Úsalo cuando el usuario pida crear un commit, redactar un mensaje de commit o revisar el texto de un commit antes de confirmarlo.
---

## Formato

Un único encabezado en imperativo, máximo 72 caracteres:

    <tipo>: <resumen en imperativo>

Tipos permitidos: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`.

## Procedimiento

1. Ejecuta `git diff --staged` para ver exactamente qué se va a confirmar.
2. Elige un único tipo. Si el diff mezcla dos tipos, propón dividir el commit.
3. Escribe el resumen describiendo el efecto, no el archivo tocado.
4. Añade cuerpo solo si el *por qué* no es evidente desde el resumen.

## Ejemplos

Bien: `fix: evitar doble envío al reintentar el pago`
Mal: `fix: cambios en PaymentService.ts`

## Casos límite

- Si no hay nada en el área de staging, dilo y detente; no ejecutes `git add`.
- Si el repositorio ya tiene un `commitlint.config.js`, esa configuración manda
  sobre este documento.

Qué hace cada parte:

• name coincide con el directorio convenciones-commit/. Requisito duro.
• description dice qué hace y cuándo usarlo. Las dos mitades son la recomendación explícita de la especificación, y son lo único que el agente ve antes de decidir si activa el skill.
• El cuerpo cubre las tres secciones recomendadas: pasos, ejemplos de entrada y salida, casos límite.

Este skill no necesita scripts/, references/ ni assets/. Añadirlos vacíos no aporta nada; el árbol canónico no es una plantilla a rellenar.

Ejemplo 2: un skill con recursos

Cuando el contenido crece, se reparte. Estructura:

informe-trimestral/
- SKILL.md
- scripts/
  - extraer.py
  - validar.sh
- references/
  - metricas.md
  - errores-api.md
- assets/
  - plantilla-informe.md

SKILL.md queda como índice operativo, no como enciclopedia:

---
name: informe-trimestral
description: Genera el informe trimestral de métricas a partir de la API de analítica interna. Úsalo cuando pidan el informe del trimestre, un resumen trimestral de métricas o una actualización de KPIs para dirección.
license: Proprietary. LICENSE.txt has complete terms
compatibility: Requires Python 3.11+, uv, and network access to the analytics API
metadata:
  author: equipo-datos
  version: "2.1"
---

## Recursos disponibles

- **`scripts/extraer.py`** — Descarga las métricas crudas del trimestre indicado.
- **`scripts/validar.sh`** — Comprueba que el JSON descargado tiene todas las series.
- **`references/metricas.md`** — Definición exacta de cada métrica y su fórmula.
- **`references/errores-api.md`** — Códigos de error de la API y cómo recuperarse.
- **`assets/plantilla-informe.md`** — Estructura obligatoria del documento final.

## Procedimiento

1. Descarga los datos del trimestre:

       uv run scripts/extraer.py --trimestre 2026-Q1 --salida datos.json

2. Valida el resultado antes de seguir:

       bash scripts/validar.sh datos.json

   Si la validación falla, lee `references/errores-api.md` y reintenta según
   el código devuelto.

3. Copia `assets/plantilla-informe.md` y rellena cada sección en orden.

4. Para cualquier métrica cuya definición no sea evidente, consulta
   `references/metricas.md`. No inventes fórmulas.

## Casos límite

- Trimestre en curso: la API devuelve datos parciales. Márcalo en el informe.
- Serie ausente: informa qué serie falta y continúa con el resto.

Los cuatro detalles que hacen que este skill funcione:

1. Los recursos se listan. La guía Using scripts lo dice explícitamente: hay que listar los scripts disponibles en SKILL.md “so the agent knows they exist”. Un archivo que nunca se menciona es un archivo que nunca se lee.
2. Se indica cuándo leer cada referencia. La guía de buenas prácticas contrasta las dos formas: “Read references/api-errors.md if the API returns a non-200 status code” is more useful than a generic “see references/ for details.” Este es el punto que decide si la divulgación progresiva funciona o no.
3. compatibility está justificado. Hay requisitos reales de entorno: Python, uv y acceso de red.
4. Todas las rutas son relativas y de un solo nivel. scripts/extraer.py, no /home/usuario/skills/informe-trimestral/scripts/extraer.py.

El capítulo 8 profundiza en cómo repartir contenido entre estos archivos.

Cómo decide el agente qué leer y cuándo

La estructura de carpetas existe para servir a un mecanismo concreto: la divulgación progresiva (progressive disclosure). La especificación define tres etapas:

1. Metadata (~100 tokens): The name and description fields are loaded at startup for all skills
2. Instructions (< 5000 tokens recommended): The full SKILL.md body is loaded when the skill is activated
3. Resources (as needed): Files (e.g. those in scripts/, references/, or assets/) are loaded only when required

La página de overview nombra esas mismas etapas como Discovery, Activation y Execution; la guía para implementadores las llama Catalog, Instructions y Resources. Son tres nomenclaturas oficiales para el mismo mecanismo.

flowchart TD
    A["Inicio de sesión"] --> B["Etapa 1 · Metadata<br/>el cliente escanea directorios<br/>y lee name + description<br/>de cada skill"]
    B --> C{"¿La tarea encaja<br/>con alguna description?"}
    C -->|No| D["El cuerpo de SKILL.md<br/>nunca se carga"]
    C -->|Sí| E["Etapa 2 · Instructions<br/>se carga el cuerpo completo<br/>de SKILL.md"]
    E --> F{"¿Las instrucciones<br/>nombran archivos?"}
    F -->|No| G["Etapa 3 · Ejecución<br/>sin recursos adicionales"]
    F -->|Sí| H["Etapa 3 · Resources<br/>el agente lee scripts/, references/<br/>o assets/ bajo demanda"]

Tres consecuencias directas para la estructura de tu skill:

La description es lo único que se carga siempre. La guía de optimización lo dice sin rodeos: “the description carries the entire burden of triggering.” Si está mal escrita, el resto del skill es inaccesible. Ese es el tema del capítulo 6.

El cuerpo se carga entero o no se carga. No hay carga parcial de SKILL.md. De ahí las 500 líneas recomendadas: es un archivo que se paga completo.

Los recursos se leen solo si el cuerpo los nombra y explica cuándo. El agente no explora el directorio por iniciativa propia. La guía para implementadores lo confirma desde el lado del cliente: una herramienta de activación dedicada puede enumerar los archivos empaquetados, pero “it should not eagerly read them. The model loads specific files on demand using its file-read tools when the skill’s instructions reference them.”

Un matiz importante sobre el disparo: la activación no es un motor de reglas del harness. La documentación es explícita en que la mayoría de implementaciones se apoyan en el juicio del propio modelo en lugar de hacer coincidencia de palabras clave. Y añade una advertencia útil: “agents typically only consult skills for tasks that require knowledge or capabilities beyond what they can handle alone”. Una petición trivial de un solo paso puede no activar un skill aunque la description encaje perfectamente.

Validar la estructura

La especificación remite a la librería de referencia:

skills-ref validate ./my-skill

This checks that your SKILL.md frontmatter is valid and follows all naming conventions.

Dos precisiones sobre esa herramienta. Primera: su propio README declara que “this library is intended for demonstration purposes only. It is not meant to be used in production.” Segunda: valida algunas cosas de forma más estricta que el texto de la especificación. Por ejemplo, rechaza cualquier campo de frontmatter fuera de los seis definidos, mientras que la especificación no declara que un campo desconocido invalide el skill. Y en el otro sentido, es más laxa en un punto: acepta skill.md en minúsculas, aunque la guía para implementadores pide buscar un archivo “named exactly SKILL.md”.

Conclusión práctica: pásale el validador, pero interpreta sus mensajes sabiendo que es una implementación de demostración, no la norma.

Errores típicos de estructura

Error	Síntoma	Corrección
name no coincide con el directorio	Incumple un requisito duro. Algunos clientes avisan y cargan igualmente; otros pueden rechazar el skill	Renombra la carpeta o el campo hasta que coincidan carácter a carácter
Mayúsculas en name	name: PDF-Processing es inválido	Solo minúsculas: pdf-processing
Guion inicial, final o doble	-pdf, pdf-, pdf--processing	Un solo guion entre segmentos, nunca en los extremos
El archivo se llama skill.md o Skill.md	Algunos clientes no lo encuentran	Nómbralo exactamente SKILL.md
SKILL.md suelto, sin carpeta propia	No hay directorio padre con el que casar name, y el descubrimiento por subdirectorios falla	Un skill es siempre nombre-del-skill/SKILL.md
Frontmatter sin abrir o sin cerrar	El parseo falla y el skill se descarta silenciosamente	La primera línea del archivo es --- y hay un --- de cierre
Dos puntos sin comillas dentro de un valor	description: Úsalo cuando: el usuario pida un PDF rompe el YAML	Entrecomilla el valor completo o usa un escalar de bloque >
description ausente o vacía	La guía para implementadores indica saltar el skill en ese caso	Escribe siempre qué hace y cuándo usarlo
Campos inventados en el frontmatter	version, author, tags o triggers en primer nivel no existen en el formato	Muévelos dentro de metadata
metadata con números o listas	El formato define un mapa de string a string	Entrecomilla los valores: version: "1.0"
allowed-tools escrito como lista YAML	El formato define una cadena separada por espacios	allowed-tools: Bash(git:*) Read
Rutas absolutas en el cuerpo	La ruta solo funciona en tu máquina	Rutas relativas desde la raíz del skill
Cadenas de referencias anidadas	El agente rara vez llega al tercer salto	Mantén las referencias a un nivel de profundidad desde SKILL.md
Recursos que nunca se mencionan en el cuerpo	Archivos que el agente no lee jamás	Lista los recursos y di cuándo consultar cada uno
SKILL.md de 1500 líneas	Se paga entero en cada activación	Mueve lo detallado a references/
Carpetas vacías scripts/, references/, assets/	Ruido sin función	El árbol canónico no es una plantilla obligatoria

Dónde vive todo esto

Una aclaración que evita confusiones desde el principio: el estándar no define dónde se instalan los skills. La frase literal de la guía para implementadores:

While the Agent Skills specification does not mandate where skill directories live (it only defines what goes inside them), scanning .agents/skills/ means skills installed by other compliant clients are automatically visible to yours, and vice versa.

.agents/skills/ es una convención ampliamente adoptada para compartir skills entre clientes, pero es convención, no norma. Lo que la especificación cubre es exclusivamente lo que hay dentro de la carpeta del skill: eso es lo que hemos visto en este capítulo. La ubicación, la instalación y el empaquetado son el tema del capítulo 10, y el empaquetado de varios skills junto a servidores MCP en una unidad distribuible se trata en el curso hermano Agent Plugins Spec. Para ver decenas de estructuras reales ya publicadas, el curso Google Skills recorre un catálogo con más de cien skills.

Resumen

• Un skill es un directorio que contiene, como mínimo, un archivo SKILL.md. Nada más es obligatorio.
• SKILL.md DEBE contener frontmatter YAML seguido de contenido Markdown, separados por delimitadores ---.
• El frontmatter define exactamente seis campos: name y description obligatorios; license, compatibility, metadata y allowed-tools opcionales. No existen version, author ni tags de primer nivel.
• name DEBE tener 1-64 caracteres, usar minúsculas, números y guiones sin duplicar ni en los extremos, y DEBE coincidir con el nombre del directorio padre.
• description DEBE tener entre 1 y 1024 caracteres, y DEBERÍA decir qué hace el skill y cuándo usarlo.
• El cuerpo Markdown no tiene restricciones de formato. Secciones recomendadas: pasos, ejemplos de entrada y salida, casos límite.
• scripts/, references/ y assets/ son convenciones recomendadas, no nombres reservados. Un skill PUEDE contener cualquier archivo o directorio adicional.
• Las referencias entre archivos usan rutas relativas desde la raíz del skill y DEBERÍAN mantenerse a un nivel de profundidad.
• La divulgación progresiva tiene tres etapas: metadata al inicio, cuerpo completo al activar, recursos solo cuando las instrucciones los nombran.
• El agente no explora la carpeta por su cuenta: si el cuerpo no menciona un recurso y no dice cuándo cargarlo, ese archivo no se lee.
• Recomendaciones frente a requisitos: 500 líneas y 5000 tokens son consejos; 64, 1024 y 500 caracteres son límites duros.
• La especificación no define dónde viven las carpetas de skills, solo qué va dentro de ellas.

Siguiente: La especificación al detalle