Qué son las Agent Skills y qué problema resuelven

Un agente moderno sabe escribir código, leer archivos, ejecutar comandos y llamar APIs. Lo que no sabe es que en tu empresa las migraciones de base de datos se aplican con un script concreto, que el endpoint /health devuelve 200 aunque la base de datos esté caída, o que el informe mensual va con tres secciones fijas y en ese orden. Ese conocimiento no está en el modelo: está en la cabeza de tu equipo, en un runbook interno o en un hilo de Slack.

Las Agent Skills son el formato abierto que empaqueta ese conocimiento en una carpeta que el agente carga cuando la necesita. Este capítulo define qué es exactamente un skill, qué problema resuelve, cómo se carga en el contexto y en qué se diferencia de las otras formas de extender un agente.

La definición, literal

La documentación oficial abre con esta frase:

Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows.

Y a continuación da la definición operativa, la que conviene memorizar:

At its core, a skill is a folder containing a SKILL.md file. This file includes metadata (name and description, at minimum) and instructions that tell an agent how to perform a specific task. Skills can also bundle scripts, reference materials, templates, and other resources.

En español neutro, sin perder ninguna pieza:

Un skill es una carpeta que contiene un archivo SKILL.md. Ese archivo lleva metadatos —como mínimo name y description— e instrucciones que le dicen a un agente cómo ejecutar una tarea concreta. Un skill también puede empaquetar scripts, material de referencia, plantillas y otros recursos.

La especificación, que es el documento normativo, lo dice todavía más corto:

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

Tres consecuencias inmediatas de esa frase:

1. La unidad es el directorio, no el archivo. Un SKILL.md suelto en una carpeta cualquiera no es un skill: el nombre del directorio es parte del contrato, porque el campo name del frontmatter debe coincidir con el nombre del directorio padre.
2. Solo SKILL.md es obligatorio. Todo lo demás es opcional.
3. No hay límite superior de contenido. La especificación dice que un directorio de skill puede contener cualquier archivo o directorio más allá del SKILL.md requerido.

La estructura canónica, tal como aparece en la especificación, en la página de inicio y en el README del repositorio oficial:

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

Ojo con la lectura de ese árbol: scripts/, references/ y assets/ no son obligatorios ni forman parte del contrato. La especificación los presenta con esta frase de apertura: “The conventions below are recommendations for organizing common types of content.” Son convenciones de organización, no requisitos. La anatomía completa de la carpeta y el detalle de cada directorio se ven en Anatomía de un skill.

Y el SKILL.md en sí tiene una única regla de forma:

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

Frontmatter YAML entre delimitadores ---, y después contenido Markdown. Sobre ese contenido, la especificación es deliberadamente permisiva: “There are no format restrictions. Write whatever helps agents perform the task effectively.”

Un skill mínimo válido cabe en cuatro líneas de metadatos:

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

El problema: agentes capaces, contexto ausente

La motivación aparece formulada en una sola frase en la documentación oficial:

Agents are increasingly capable, but often don’t have the context they need to do real work reliably.

El diagnóstico no es “los agentes no saben lo suficiente”. Es que el conocimiento que les falta es de un tipo específico: procedimental y particular. La misma fuente identifica el remedio y sus tres ejes:

Skills solve this by packaging procedural knowledge and company-, team-, and user-specific context into portable, version-controlled folders that agents load on demand.

Vale la pena desmontar esa oración, porque cada pieza es una decisión de diseño:

Pieza de la definición	Qué implica en la práctica
procedural knowledge	No datos, sino procedimientos: en qué orden se hacen las cosas, qué se valida antes de continuar, qué se hace cuando falla el paso 3
company-, team-, and user-specific	Contexto que ningún modelo puede haber aprendido en el entrenamiento porque es privado o particular de un grupo
portable	La misma carpeta funciona en cualquier agente compatible con el formato
version-controlled	Es texto en archivos, así que vive en Git con historial, revisión y ramas
load on demand	No se paga el coste en contexto hasta que la tarea lo pide

El contraste con el modelo base es el criterio de corte que después se convierte en la regla de autoría central del curso: añadir lo que al agente le falta, omitir lo que ya sabe. La guía de buenas prácticas lo expresa como un test directo, “Would the agent get this wrong without this instruction?”, y remata con el ejemplo: no hace falta explicarle a un agente qué es un PDF, cómo funciona HTTP o qué hace una migración de base de datos. Ese criterio se trabaja en detalle en Escribir buenas instrucciones.

Los tres beneficios declarados

La documentación nombra exactamente tres beneficios. No son una lista de marketing abierta: conviene citarlos como están porque cada uno responde a una pregunta distinta.

1. Domain expertise (experiencia de dominio)

Capture specialized knowledge — from legal review processes to data analysis pipelines to presentation formatting — as reusable instructions and resources.

Responde a ¿qué se captura?. Conocimiento especializado, y los tres ejemplos oficiales son deliberadamente heterogéneos: un proceso de revisión legal, un pipeline de análisis de datos y un formato de presentaciones. Ninguno de los tres es “programar”. El formato no es una herramienta de desarrolladores; es una herramienta de dominio.

2. Repeatable workflows (flujos repetibles)

Turn multi-step tasks into consistent, auditable procedures.

Responde a ¿qué gana el proceso?. Dos adjetivos cargados: consistent, el mismo procedimiento en cada ejecución en lugar de una improvisación distinta cada vez; y auditable, alguien puede leer el SKILL.md, revisarlo en un pull request y saber exactamente qué se le pidió al agente.

3. Cross-product reuse (reutilización entre productos)

Build a skill once and use it across any skills-compatible agent.

Responde a ¿dónde vale?. Es el beneficio que solo existe porque el formato es un estándar abierto y no la configuración propietaria de un producto. Un skill escrito para tu equipo funciona igual en el agente de terminal, en el del editor y en el de la nube, siempre que todos implementen el formato. El mapa de esos clientes es el tema de El ecosistema.

Progressive disclosure: las tres etapas

Aquí está el mecanismo que hace que la idea escale. Si un agente cargara todos sus skills completos al iniciar, veinte skills serían veinte juegos de instrucciones compitiendo por el contexto antes de que el usuario escriba nada. La divulgación progresiva (progressive disclosure) evita eso cargando la información por capas.

La documentación de referencia lo describe así:

Agents load skills through progressive disclosure, in three stages:

1. Discovery: At startup, agents load only the name and description of each available skill, just enough to know when it might be relevant.
2. Activation: When a task matches a skill’s description, the agent reads the full SKILL.md instructions into context.
3. Execution: The agent follows the instructions, optionally executing bundled code or loading referenced files as needed.

Las tres etapas, con su nombre oficial y lo que ocurre en cada una:

Etapa 1 — Discovery (descubrimiento)

Al arrancar la sesión, el agente carga solo name y description de cada skill disponible. Nada más. Lo justo para saber cuándo podría ser relevante.

La especificación cuantifica esta etapa como ~100 tokens por skill bajo el nombre de Metadata. La guía para implementadores de clientes la llama Catalog y la estima en ~50-100 tokens por skill.

Consecuencia directa de diseño: como en esta etapa el agente solo ve la description, ese campo carga todo el peso del disparo. Una description pobre significa un skill que nunca se activa por bueno que sea su contenido. Ese problema tiene un capítulo entero: La description.

Etapa 2 — Activation (activación)

Cuando la tarea coincide con la description, el agente lee el cuerpo completo del SKILL.md al contexto. La especificación llama a esta etapa Instructions y le pone una cifra orientativa: menos de 5000 tokens recomendado.

La advertencia asociada, literal de la especificación, es la que gobierna cómo se escribe un SKILL.md:

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.

Es todo o nada: no se carga media instrucción. Por eso la recomendación de mantener el SKILL.md principal por debajo de 500 líneas y mover el material extenso a archivos aparte.

Etapa 3 — Execution (ejecución)

El agente sigue las instrucciones y, opcionalmente, ejecuta el código empaquetado o carga los archivos referenciados solo cuando hacen falta. La especificación llama a esta etapa Resources y la temporiza como “as needed”: archivos en scripts/, references/ o assets/ se cargan únicamente cuando se requieren.

flowchart TD
    A["Inicio de sesión"] --> B["Etapa 1 · Discovery<br/>solo name y description<br/>de cada skill instalado"]
    B --> C{"¿La tarea coincide<br/>con alguna description?"}
    C -->|No| D["El skill nunca se carga<br/>coste: solo su metadata"]
    C -->|Sí| E["Etapa 2 · Activation<br/>cuerpo completo de SKILL.md<br/>menos de 5000 tokens recomendado"]
    E --> F{"¿Las instrucciones<br/>referencian recursos?"}
    F -->|No| G["Etapa 3 · Execution<br/>el agente sigue las instrucciones"]
    F -->|Sí| H["Etapa 3 · Execution<br/>carga bajo demanda de<br/>scripts, references y assets"]
    H --> G

Los tres juegos de nombres

Un detalle que confunde al leer la documentación oficial: las mismas tres etapas tienen tres juegos de nombres, según el documento que se esté leyendo. No son mecanismos distintos.

Documento	Etapa 1	Etapa 2	Etapa 3
Especificación (normativa)	Metadata — ~100 tokens	Instructions — menos de 5000 tokens recomendado	Resources — cuando se requieren
Página de inicio, README y quickstart	Discovery	Activation	Execution
Guía de implementación de clientes	Catalog — ~50-100 tokens por skill	Instructions — al activar	Resources — cuando las instrucciones los referencian

En este curso se usan los nombres descubrimiento, activación y ejecución, y se indica el nombre normativo cuando el punto tratado sea una restricción de la especificación.

Por qué esto permite tener muchos skills

La conclusión que la propia documentación saca del mecanismo:

Full instructions load only when a task calls for them, so agents can keep many skills on hand with only a small context footprint.

Y la formulación cuantitativa de la guía para implementadores:

An agent with 20 installed skills doesn’t pay the token cost of 20 full instruction sets upfront — only the ones actually used in a given conversation.

El coste fijo de tener un skill instalado es su metadata. El coste variable —el cuerpo, y después los recursos— solo se paga en las conversaciones donde de verdad se usa. Es lo que separa “tengo tres skills” de “tengo un catálogo de cincuenta skills disponibles”.

Origen: desarrollado por Anthropic, liberado como estándar abierto

La procedencia del formato está declarada de forma explícita, y conviene citarla con precisión porque es fácil deformarla en cualquiera de las dos direcciones:

The Agent Skills format was originally developed by Anthropic, released as an open standard, and has been adopted by a growing number of agent products. The standard is open to contributions from the broader ecosystem.

Cuatro hechos, ni uno más:

1. El formato lo desarrolló originalmente Anthropic.
2. Se liberó como estándar abierto.
3. Lo han adoptado un número creciente de productos de agentes.
4. El estándar está abierto a contribuciones del ecosistema en general.

El desarrollo ocurre a la vista: el repositorio vive en github.com/agentskills/agentskills, con Issues para errores concretos y Discussions para propuestas y preguntas de diseño, y hay un servidor de Discord enlazado desde el propio README para compartir lo que se está construyendo. El código del repositorio está bajo Apache 2.0 y la documentación bajo CC-BY-4.0.

El CONTRIBUTING.md fija además dos límites que evitan expectativas erróneas desde el capítulo uno:

• La barra para añadir cosas a la especificación es alta, por diseño: “it is much easier to add things to a specification than to remove them”. Las propuestas deben venir de un problema real de implementación, no de una preocupación teórica.
• No existe un directorio oficial de skills de la comunidad. El repositorio declara explícitamente que no acepta envíos de skills. Lo que sí existe es una lista de clientes que implementan el formato, con un criterio de entrada concreto: el producto debe estar públicamente disponible y ser capaz de descubrir y ejecutar skills hoy; no se listan productos que solo hayan anunciado la intención de soportarlos ni los que estén en beta privada.

Dos precisiones para no exagerar en ninguna dirección: el estándar no es propiedad exclusiva de un cliente concreto —lo implementan editores, CLIs, plataformas cloud, frameworks y hasta aplicaciones móviles—, y a la vez no todo comportamiento que veas en tu agente favorito es parte del estándar. La especificación define qué va dentro de la carpeta; muchas decisiones visibles —dónde se instalan los skills, cómo se activan, si el modelo ve o no el frontmatter— las toma cada cliente. Esa frontera se traza entera en El ecosistema.

Cómo se lee el lenguaje normativo

La especificación usa las formas verbales must, should y may en minúscula, sin declararse adherida a RFC 2119. En este curso se traducen así, y la distinción importa porque separa lo que se valida de lo que se sugiere:

Original	Traducción en este curso	Significado
must	DEBE	Requisito duro. Incumplirlo hace el skill inválido
should	DEBERÍA	Recomendación fuerte. No incumplirla no invalida nada
may	PUEDE	Permiso explícito. Ni obligatorio ni recomendado

Ejemplo de las tres en la misma especificación: el name DEBE (must) tener entre 1 y 64 caracteres; la description DEBERÍA (should) describir tanto qué hace el skill como cuándo usarlo; un directorio de skill PUEDE (may) contener cualquier archivo adicional más allá del SKILL.md requerido.

Cada vez que este curso diga “la especificación exige”, habrá un must detrás. Si solo hay una recomendación, se dirá que es una recomendación. La lista completa de requisitos está en La especificación al detalle.

En qué se diferencia de las otras formas de extender un agente

Un skill no es la única manera de darle capacidades nuevas a un agente, y la mayoría de los productos que soportan skills soportan también las demás. Elegir mal el mecanismo es la fuente más común de frustración: se acaba escribiendo un skill donde hacía falta una herramienta, o metiendo en el prompt de sistema algo que debía cargarse bajo demanda.

flowchart TD
    Q{"¿Qué le falta<br/>al agente?"}
    Q -->|"Una regla que aplica<br/>siempre, en toda tarea"| SP["Prompt de sistema<br/>coste permanente de contexto"]
    Q -->|"Una capacidad que el modelo<br/>no puede ejecutar por sí solo"| T["Herramienta<br/>ejecuta y devuelve datos"]
    Q -->|"Acceso a un sistema externo<br/>expuesto por un servidor"| M["MCP<br/>protocolo cliente-servidor"]
    Q -->|"Aislar una tarea en<br/>su propio contexto"| S["Subagente<br/>sesión separada"]
    Q -->|"Un procedimiento que aplica<br/>solo a cierto tipo de tarea"| SK["Agent Skill<br/>carpeta cargada bajo demanda"]

La comparación en detalle:

Mecanismo	Qué aporta	Cuándo se carga	Formato	Ejecuta código
Prompt de sistema	Reglas e identidad que valen para toda la sesión	Siempre, desde el primer token	Depende del cliente	No
Herramienta	Una capacidad que el modelo invoca con argumentos	Su definición está siempre presente; se ejecuta cuando el modelo la llama	Esquema de la herramienta, definido por el cliente o el SDK	Sí, por definición
Servidor MCP	Acceso a datos y acciones de un sistema externo	El cliente conecta el servidor y expone sus herramientas y recursos	Protocolo cliente-servidor, con proceso o endpoint propio	Sí, en el servidor
Subagente	Aislamiento: una tarea corre en su propio contexto y devuelve un resumen	Cuando el agente principal delega	Depende del cliente	Según sus herramientas
Agent Skill	Conocimiento procedimental y contexto específico	Metadata al inicio; instrucciones al activar; recursos bajo demanda	Carpeta con SKILL.md, estándar abierto	Solo si el skill empaqueta scripts y el agente los ejecuta

Las distinciones que más veces se confunden:

Skill vs. prompt de sistema. Lo que va en el prompt de sistema se paga en cada conversación, la use o no. Un skill se paga en metadata siempre y en instrucciones solo cuando la tarea lo pide. La pregunta de corte es: ¿esto aplica a todo lo que hago con el agente, o solo a cierto tipo de tarea? Si es lo segundo, es un skill.

Skill vs. herramienta. Una herramienta es una capacidad: le da al modelo algo que ejecutar y devolver. Un skill es conocimiento: le dice al modelo cómo usar las capacidades que ya tiene. Un skill que necesita ejecutar algo no define una herramienta nueva: empaqueta un script en scripts/ y le indica al agente que lo corra con su herramienta de ejecución. La especificación es explícita en que los lenguajes soportados en scripts/ dependen de la implementación del agente, y las opciones comunes son Python, Bash y JavaScript. El tema completo está en Scripts y comandos dentro de un skill.

Skill vs. MCP. MCP es un protocolo cliente-servidor: hay un proceso o endpoint corriendo que expone herramientas y recursos, con su propio ciclo de vida, autenticación y transporte. Un skill es texto en una carpeta, sin proceso, sin red y sin runtime. Resuelven problemas complementarios: MCP conecta al agente con un sistema; un skill le enseña el procedimiento para usarlo bien. Un servidor MCP de la base de datos de la empresa más un skill que documenta sus convenciones —qué tablas usan borrado lógico, qué columna es realmente el identificador de usuario— es la combinación natural, no una redundancia. De hecho, el formato hermano de plugins empaqueta ambas cosas juntas: eso se ve en Agent Plugins Spec.

Skill vs. subagente. Un subagente es un mecanismo de aislamiento de contexto, no de conocimiento. Los dos se combinan: la guía para implementadores describe la delegación a subagente como un patrón donde las instrucciones del skill se ejecutan en una sesión separada que devuelve un resumen a la conversación principal. Importante para no confundir estándar con producto: esa guía la marca explícitamente como un patrón avanzado soportado solo por algunos clientes, no como parte del formato.

Qué cubre este curso

Doce capítulos que van del formato a la implementación, en este orden:

#	Capítulo	Qué resuelve
1	Qué son las Agent Skills	Definición, problema, progressive disclosure, origen
2	Anatomía de un skill	SKILL.md y la estructura de carpetas pieza por pieza
3	La especificación al detalle	Los seis campos del frontmatter y todos sus límites
4	Tu primer skill paso a paso	Crear uno, verlo activarse, validarlo
5	Escribir buenas instrucciones	Alcance, nivel de detalle y calibración del control
6	La description	Que el skill dispare cuando debe y solo cuando debe
7	Scripts y comandos	Código empaquetado y diseñado para uso agéntico
8	Referencias y recursos	Progressive disclosure avanzada dentro del skill
9	Evaluar la calidad	Evals, baseline sin skill y grading con evidencia
10	Distribución e instalación	Dónde viven los skills y cómo llegan al agente
11	El ecosistema de clientes	Quién lo implementa y en qué se diferencian
12	Implementar soporte en tu agente	Descubrir, parsear, divulgar, activar y gestionar contexto

Los capítulos 1 a 4 son la base. Del 5 al 9 está el trabajo de autoría, que es donde se decide si un skill sirve. Del 10 al 12, la distribución y el lado del cliente.

Los dos cursos hermanos

Este curso forma una trilogía con otros dos, y cada uno cubre una capa distinta:

• Agent Plugins Spec — La capa de empaquetado. Un plugin agrupa varios skills y servidores MCP en una unidad distribuible con su propio manifiesto. Es lo que sigue naturalmente cuando ya tienes más de un skill y quieres repartirlos como un conjunto.
• Google Skills — El catálogo oficial de skills de Google, con más de 100 skills reales. Es el mejor material para estudiar cómo se ve el formato aplicado a escala en producción, en lugar de en ejemplos de juguete.

El orden recomendado es este curso primero —porque define el formato que los otros dos usan—, después plugins si te interesa distribuir, y el catálogo de Google en cualquier momento como fuente de ejemplos.

Resumen

• Un skill es una carpeta que contiene un archivo SKILL.md con metadatos —como mínimo name y description— e instrucciones que le dicen a un agente cómo ejecutar una tarea. Puede empaquetar además scripts, referencias y plantillas.
• El SKILL.md DEBE (must) contener frontmatter YAML seguido de contenido Markdown. El cuerpo Markdown no tiene restricciones de formato.
• El problema que resuelven: los agentes son cada vez más capaces pero les falta el contexto procedimental y específico de la empresa, el equipo y la persona. Los skills lo empaquetan en carpetas portables, versionadas y cargadas bajo demanda.
• Los tres beneficios declarados son experiencia de dominio, flujos repetibles y reutilización entre productos.
• Progressive disclosure en tres etapas: descubrimiento —solo name y description, ~100 tokens—, activación —cuerpo completo del SKILL.md, menos de 5000 tokens recomendado— y ejecución —scripts, referencias y assets cargados solo cuando se requieren.
• Ese mecanismo es lo que permite tener muchos skills con una huella de contexto pequeña: un agente con 20 skills instalados no paga por adelantado 20 juegos completos de instrucciones, solo los que se usan en cada conversación.
• El formato lo desarrolló originalmente Anthropic, se liberó como estándar abierto y su desarrollo es abierto en GitHub y Discord, con una barra alta y deliberada para añadir cosas a la especificación.
• Un skill no es un prompt de sistema —que se paga siempre—, ni una herramienta —que es capacidad, no conocimiento—, ni un servidor MCP —que es un proceso con protocolo propio—, ni un subagente —que es aislamiento de contexto. Se combinan bien entre sí.
• scripts/, references/ y assets/ son convenciones recomendadas, no requisitos del formato.

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