Qué es una agent skill y cómo funciona realmente

Qué es realmente una habilidad de agente

Una habilidad de agente es una carpeta del disco que contiene un archivo llamado SKILL.md. Ese archivo incluye un nombre, una descripción breve e instrucciones escritas en Markdown sin formato especial. El agente carga la descripción al iniciarse y lee las instrucciones sólo cuando la solicitud coincide con esa descripción. Casi todo lo demás relacionado con las habilidades se deriva de esas dos frases.

La carpeta puede contener más de un archivo. La especificación Agent Skills define tres directorios opcionales: scripts/ para el código que ejecuta el agente, references/ para los documentos que lee cuando los necesita y assets/ para las plantillas y los datos. Ninguno es obligatorio. Una carpeta que sólo contiene un archivo SKILL.md es una habilidad completa.

restore-drill/
  SKILL.md
  references/retention-policy.md
  scripts/verify_snapshot.sh

La descripción es la parte que más se suele subestimar. Es el único texto que el agente ve antes de decidir si abre la habilidad, por lo que debe indicar qué hace la habilidad y cuándo se debe usar, con las palabras que una persona escribiría realmente.

Por qué una skill apenas cuesta contexto hasta que se utiliza

Este es el argumento que hace que el formato merezca la pena, y trata sobre el contexto, no sobre las funciones. La carga se realiza por etapas, lo que la especificación denomina divulgación progresiva.

Al iniciar, el agente carga el name y el description de cada skill instalada, y nada más. La especificación Agent Skills sitúa ese coste en aproximadamente 100 tokens por skill, según las recomendaciones publicadas en agosto de 2026. Si instala una docena de skills, habrá consumido aproximadamente el contexto de un párrafo largo.

Cuando una solicitud coincide con una descripción, el agente lee el cuerpo de esa única SKILL.md. La especificación recomienda mantener el cuerpo por debajo de 5.000 tokens y el archivo por debajo de 500 líneas. Los archivos de references/ y scripts/ siguen sin consumir contexto en este punto. Un archivo de referencia sólo se carga si las instrucciones dirigen al agente hacia él. Un script incluido funciona de otra forma: el agente lo ejecuta mediante el shell, por lo que el código fuente del script nunca entra en la ventana de contexto y sólo lo hace su salida.

Compare esto con lo primero que suele elegirse: un prompt enorme. Cada línea de un prompt del sistema o de un archivo de instrucciones siempre activo se procesa en cada solicitud y en cada sesión, tanto si la tarea la necesita como si no, y compite por la atención con la pregunta real. Diez mil tokens de instrucciones permanentes son un coste que se paga incluso para preguntar qué hora es. Una docena de skills cuesta alrededor de 1.200 tokens en reposo y sólo aumenta para la tarea que las necesita. Ese es el argumento completo a favor de las skills y la razón por la que una biblioteca pequeña supera a un prompt más largo.

Hay una salvedad que suele pasarse por alto. Cuando se carga una skill, su cuerpo permanece en el contexto durante el resto de la sesión, por lo que un SKILL.md largo genera un coste recurrente y no un coste único. Mover los detalles a references/ no es una cuestión de orden. Es el mecanismo funcionando según lo diseñado.

Una skill del agente no es una llamada a una herramienta

Una herramienta, también llamada llamada a una función, es algo que el modelo puede invocar. El entorno de ejecución envía al modelo un esquema con un nombre, una descripción y la estructura de los argumentos. El modelo emite una llamada, el código la ejecuta y el resultado vuelve como un mensaje. Las herramientas hacen cosas.

Una skill no ejecuta nada por sí sola. El agente la lee y después actúa usando las herramientas que ya tiene. El modelo no puede pasar argumentos a una skill como los pasa a una herramienta. Una skill puede indicar al modelo qué herramientas debe usar, en qué orden y qué debe comprobar después.

En resumen: una herramienta proporciona al agente una capacidad nueva, y una skill le proporciona criterio para usar una capacidad que ya tiene. Si un paso debe producir siempre un resultado exacto y validado, necesita una herramienta o un script. Si un paso requiere aplicar el mismo razonamiento de forma coherente, necesita una skill.

Una habilidad de agente no es un servidor MCP

MCP (model context protocol) es un protocolo para conectar un agente con un sistema externo. Un servidor MCP es un proceso que se ejecuta, utiliza ese protocolo y expone herramientas al agente. Normalmente necesita configuración, credenciales y un comando local o un endpoint de red. Una habilidad es una carpeta que contiene un archivo Markdown. No hay ningún proceso, puerto ni protocolo.

El coste de contexto también difiere. Cada herramienta que expone un servidor MCP incluye un nombre, una descripción y un esquema de argumentos. De forma predeterminada, estos elementos se incluyen en las solicitudes durante toda la sesión, se utilicen o no. Algunos clientes han empezado a obtener los esquemas de las herramientas bajo demanda, pero cargarlos al inicio sigue siendo lo habitual. Una habilidad almacenada ocupa una línea de texto.

Ambos elementos se complementan, y las configuraciones más sólidas utilizan los dos. El servidor MCP proporciona el acceso. La habilidad proporciona el procedimiento: qué herramientas llamar para el flujo de trabajo real de su equipo, en qué orden y cómo debe ser un buen resultado. Si aloja su propio servidor, ejecutar servidores MCP en un VPS cubre esa parte.

Una habilidad de agente no es un prompt del sistema ni un AGENTS.md

Ambos son instrucciones en Markdown, por lo que es normal confundirlos. AGENTS.md, CLAUDE.md y el prompt del sistema están siempre activos. Una habilidad se activa cuando es necesaria.

La prueba consiste en una sola pregunta: ¿sería incorrecto ignorar este párrafo en una tarea que no tiene relación con él? La guía de estilo, el comando de compilación y la regla de nomenclatura de ramas se aplican a todas las tareas, por lo que deben estar en el archivo siempre activo. El objetivo es que se cargue cada vez. La lista de comprobación de la versión, que se ejecuta dos veces al mes, no se aplica a todas las tareas, por lo que debe estar en una habilidad. Cuando una sección del archivo siempre activo se convierte en un procedimiento numerado, es una señal de que debe trasladarse.

Estos archivos también tienen convenciones propias que conviene aplicar correctamente. Consulte qué debe incluirse en AGENTS.md y qué debe incluirse en el archivo para personas y un design.md que explica la estructura de un código base para conocer los dos que usamos.

Cómo es una skill mínima

En Claude Code, las skills personales se encuentran en ~/.claude/skills/<name>/SKILL.md y se aplican a todos tus proyectos. Las skills del proyecto se encuentran en .claude/skills/<name>/SKILL.md y se incorporan al repositorio git, por lo que todas las personas y todos los agentes que trabajan en ese repositorio las tienen disponibles. GitHub Copilot y VS Code leen las skills del espacio de trabajo desde .github/skills/. El archivo que contiene es el mismo.

mkdir -p ~/.claude/skills/restore-drill

---
name: restore-drill
description: Run a restic restore drill and report what was recovered. Use when the user asks to test backups, verify a restore, or check that a snapshot is readable.
---

# Restore drill

1. Run `restic snapshots` and pick the newest snapshot for the host in question.
2. Restore it into a scratch directory under `/tmp`, never over live data.
3. Compare the restored file count and total size against the snapshot summary.
4. Report the snapshot ID and anything that failed to restore.

If `restic snapshots` prints `Fatal: unable to open config file`, the repository path or the password is wrong. Stop and report that instead of guessing.

Eso es una skill completa. El nombre del directorio se convierte en el comando que debes escribir, por lo que esta es /restore-drill. En Claude Code, el menú /skills muestra lo que está instalado. Es la forma más rápida de confirmar que se ha cargado el archivo. Si no aparece en ese menú, hay un nombre incorrecto: el archivo debe llamarse SKILL.md y el nombre del directorio debe contener sólo letras minúsculas, dígitos y guiones simples. El mismo procedimiento, escrito para que el agente pueda volver a ejecutarlo, es un complemento natural de las copias de seguridad programadas de restic en un VPS, porque ejecutar la copia de seguridad no equivale a restaurarla.

Cuándo una habilidad debe ser un script

Cualquier paso que tenga siempre una única respuesta correcta debe ser un script. La habilidad debe limitarse a unas pocas líneas que indiquen cuándo ejecutarlo y cómo interpretar la salida. Hay dos motivos, y ambos son prácticos.

En primer lugar, el código fuente de un script nunca entra en la ventana de contexto. Un analizador de 300 líneas sólo consume su salida, mientras que la misma lógica escrita como instrucciones Markdown consume toda su extensión cada vez que se carga la habilidad.

En segundo lugar, un script produce la misma respuesta dos veces. Si se pide a un modelo que vuelva a derivar la misma regla de análisis de registros en cada ejecución, un mal día puede obtener una variante ligeramente distinta. El problema no se detectará hasta que dos cifras no coincidan.

Por tanto, divida el trabajo según su naturaleza. «Analizar el CSV e imprimir cada fila cuyo total no coincida con las partidas» es una tarea para un script. «Revisar las filas que imprimió el script y explicar cuáles parecen errores de introducción de datos» es una instrucción de la habilidad. Mantener el criterio en Markdown y el comportamiento determinista en el código responde al mismo principio que crear un bucle que un agente pueda ejecutar sin supervisión.

¿Por qué mi skill nunca se activa?

Porque su description indica qué hace el skill, pero nunca cuándo debe usarse. Esa línea es lo único que el agente puede comparar con su solicitud. «Ayuda con tareas de bases de datos» no coincide con nada concreto. «Ejecuta una migración de esquema en la base de datos de staging. Úsalo cuando el usuario solicite migrar una tabla, añadir una columna o cambiar un esquema» contiene las palabras que una persona escribe realmente, por lo que se activa.

El fallo contrario es el skill que se activa constantemente. Una descripción como «Úsalo para cualquier cambio de código en este repositorio» coincide con todo, por lo que el cuerpo se carga en cada tarea y permanece en el contexto durante el resto de la sesión. Limite la descripción al caso que realmente quiere cubrir. En Claude Code también puede establecer disable-model-invocation: true en el frontmatter. Esto detiene la carga automática y mantiene el skill disponible cuando escribe su nombre.

El tercer fallo es el skill que duplica una herramienta. Las instrucciones que indican al agente que curl una API que su servidor MCP ya expone, o que busque en los archivos con grep cuando el harness tiene una herramienta de búsqueda, crean un proceso más lento y dos conjuntos de instrucciones que pueden entrar en conflicto. Elimine la duplicación y describa la intención.

No intente adivinar cuál de los tres casos tiene. Ejecute la misma solicitud dos veces en una sesión nueva: una vez con el skill disponible y otra con él desactivado. Después, compare las respuestas. La sesión nueva es importante porque la sesión en la que escribió el skill ya contiene todo lo que este indica, lo que oculta las carencias de la versión escrita. El plugin skill-creator de Anthropic automatiza esta comparación dentro de Claude Code. También genera solicitudes que deberían activar el skill y otras que no deberían hacerlo, y mide con qué frecuencia se activa en cada caso.

¿Es el formato de un proveedor o un estándar?

Anthropic publicó el formato a finales de 2025 y después lo presentó como un estándar abierto alojado en agentskills.io. En agosto de 2026, esa especificación define los campos obligatorios name y description, los campos opcionales license, compatibility, metadata y allowed-tools, los tres directorios opcionales y el comportamiento de carga por etapas. También incluye un validador de referencia, por lo que skills-ref validate ./my-skill comprueba una carpeta con respecto a la especificación antes de compartirla.

La lista de clientes es el indicador real. Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands y opencode, entre otros, leen la misma carpeta. Microsoft publica sus propias skills en este formato en github.com/microsoft/skills y ofrece una herramienta de escritorio llamada Skill Recorder. Esta herramienta observa cómo se realiza una tarea una vez, la reconstruye como una intención con pasos ordenados y escribe el resultado como una skill. Que un proveedor desarrolle un grabador cuyo formato de salida pertenece a la especificación de otro proveedor indica que el formato ha dejado de ser una función exclusiva de un producto.

Qué escribir primero

No planifique una biblioteca. Espere hasta darse cuenta de que ha pegado las mismas instrucciones en un chat por tercera vez y, entonces, mueva ese texto a un SKILL.md y elimine el texto pegado. La repetición que ya ha experimentado es el único desencadenante fiable para conservar una habilidad. Un procedimiento de búsqueda es una buena primera opción, y una habilidad de búsqueda respaldada por su propia instancia de SearXNG muestra cómo debe ser.

Dos hábitos mantienen la biblioteca en buen estado. Lea todas las habilidades que no haya escrito antes de instalarlas, incluidos los scripts, porque una habilidad contiene instrucciones que seguirá su agente y código que puede ejecutar: trátela como si instalara software de un desconocido. Mantenga también las credenciales fuera de la carpeta, porque una habilidad es un archivo de texto que se confirma en un repositorio y se comparte. Cómo mantener los secretos alejados de sus agentes explica dónde deben estar esos valores, y la hoja de ruta para aprender sobre agentes este año ordena las habilidades junto con el resto de la configuración.

FAQ

¿Cuál es la diferencia entre una habilidad de agente y un servidor MCP?

Un servidor MCP (model context protocol) es un proceso en ejecución que expone herramientas a un agente mediante un protocolo. Por tanto, necesita configuración y credenciales, y las definiciones de sus herramientas normalmente ocupan contexto durante toda la sesión, aunque no se utilicen. Una habilidad de agente es una carpeta que contiene un archivo SKILL.md. No requiere procesos ni protocolos y consume alrededor de 100 tokens hasta que el agente decide leerla. Use un servidor MCP para dar acceso a un sistema a un agente. Use una habilidad para indicarle el procedimiento adecuado para utilizar ese acceso. Muchas configuraciones utilizan ambos.

¿Las habilidades de agente sólo funcionan con Claude Code?

No. Anthropic desarrolló el formato y después lo publicó como estándar abierto en agentskills.io. La misma carpeta puede ser leída por Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands y otros clientes. Lo que cambia es dónde busca cada cliente y qué campos adicionales de frontmatter entiende. Claude Code lee ~/.claude/skills/ y .claude/skills/, mientras que GitHub Copilot y VS Code leen .github/skills/ en el repositorio. El archivo SKILL.md no cambia al pasar de un cliente a otro.

¿Cuántas habilidades puedo instalar antes de que el sistema se ralentice?

La restricción está en el presupuesto de inicio, no en una cantidad concreta. Cada habilidad instalada aporta su nombre y descripción, aproximadamente 100 tokens según las directrices publicadas en la especificación. Por tanto, treinta habilidades consumen unos 3,000 tokens antes de utilizar ninguna. Lo primero que se degrada es la selección, no la velocidad: muchas habilidades con descripciones solapadas dificultan que el modelo elija la correcta. Escriba descripciones que no se solapen y elimine las habilidades que haya dejado de utilizar.

¿Debo poner esta instrucción en una habilidad o en AGENTS.md?

Pregúntese si se aplica a todas las tareas del repositorio. Los comandos de compilación, el estilo del proyecto y las reglas de nombres se aplican a todas ellas, por lo que deben estar en el archivo que siempre se carga. Ese es precisamente el objetivo de cargarlo cada vez. Un procedimiento que se ejecuta ocasionalmente, como una lista de comprobación de una versión o un procedimiento de restauración, debería ser una habilidad. Así no tiene ningún coste en las tareas que no lo necesitan. Una sección de AGENTS.md que se haya convertido en una serie de pasos numerados suele ser una habilidad que está esperando a trasladarse.