Qué es una habilidad de agente y cómo funciona

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 sólo lee las instrucciones 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 plantillas y datos. Ninguno es obligatorio. Una carpeta que sólo contenga un 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 ve el agente 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 cuesta casi nada hasta que se usa

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 iniciarse, el agente carga el name y el description de cada skill instalada, y nada más. La especificación de Agent Skills sitúa ese coste en aproximadamente 100 tokens por skill (según las directrices 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 contenido de ese SKILL.md. La especificación recomienda mantener el contenido por debajo de 5,000 tokens y el archivo por debajo de 500 líneas. Los archivos de references/ y scripts/ siguen sin tener coste en este momento. 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.

Ahora compárelo con aquello a lo que la gente recurre primero: un prompt enorme. Cada línea de un prompt de sistema o de un archivo de instrucciones que siempre está activo se paga en cada solicitud y en cada sesión, aunque la tarea no la necesite, y compite por la atención con la pregunta real. Diez mil tokens de instrucciones permanentes son una factura que 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 todo el argumento a favor de las skills, y por eso una biblioteca pequeña supera a un prompt más largo.

Hay una salvedad que suele pasar desapercibida. Cuando se carga una skill, su contenido permanece en el contexto durante el resto de la sesión, por lo que un SKILL.md largo supone 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 previsto.

Una skill de agente no es una llamada a una herramienta

Una herramienta, también llamada llamada de función, es algo que el modelo puede invocar. El sistema proporciona al modelo un esquema: 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 mensaje. Las herramientas hacen cosas.

Una skill no ejecuta nada por sí sola. El agente la lee y después actúa mediante 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, mientras que 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 skill puede consistir únicamente en criterio y, aun así, ser la que más utilice, como muestra Ponytail, que hace que un agente de programación aplique el cambio mínimo que funciona: no añade ninguna capacidad nueva y sólo modifica la forma en que el agente usa las capacidades que ya tiene.

Un skill 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, habla ese protocolo y expone herramientas al agente. Normalmente necesita configuración, credenciales y un comando local o un endpoint de red. Un skill es una carpeta que contiene un archivo Markdown. No hay ningún proceso, puerto ni protocolo.

El coste de contexto difiere de la misma forma. 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 la solicitud durante toda la sesión, se usen o no. Algunos clientes han empezado a obtener los esquemas de herramientas bajo demanda, pero cargarlos al principio sigue siendo lo habitual. Un skill almacenado ocupa una sola línea de texto.

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

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

Ambos son instrucciones en Markdown, por lo que es normal confundirlos. La diferencia está en cuándo se cargan. AGENTS.md, CLAUDE.md y el mensaje del sistema están siempre activos. Una habilidad se activa bajo demanda.

La prueba consiste en una pregunta: ¿sería incorrecto ignorar este párrafo en una tarea que no tiene relación con él? La guía de estilo del proyecto, el comando de compilación y la regla para nombrar ramas se aplican a todas las tareas, por lo que deben estar en el archivo que siempre se carga. Ese es precisamente el objetivo de cargarlo cada vez. La lista de comprobación de publicació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 que siempre se carga 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 habilidad mínima

En Claude Code, las habilidades personales se guardan en ~/.claude/skills/<name>/SKILL.md y se aplican a todos tus proyectos. Las habilidades del proyecto se guardan en .claude/skills/<name>/SKILL.md y se incluyen en git, de modo que todas las personas y todos los agentes que trabajen en ese repositorio las tienen disponibles. GitHub Copilot y VS Code leen las habilidades del espacio de trabajo desde .github/skills/. El archivo que contienen 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.

Esta es una habilidad completa. El nombre del directorio se convierte en el comando que debes escribir, por lo que este comando 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 detectado el archivo. Si no aparece en ese menú, hay un nombre incorrecto: el archivo debe llamarse SKILL.md, y el nombre del directorio debe usar letras minúsculas, dígitos y guiones simples. El mismo procedimiento, escrito para que tu agente pueda volver a ejecutarlo, complementa de forma natural las copias de seguridad programadas con restic en un VPS, porque que la copia se ejecute no significa que se pueda restaurar.

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 deducir la misma regla de análisis de registros en cada ejecución, un mal día puede hacerlo de forma 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 todas las filas cuyo total no coincida con las partidas» es un script. «Revisar las filas que ha impreso el script y explicar cuáles parecen un error 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 sigue el mismo principio que crear un bucle que un agente pueda ejecutar sin supervisión.

¿Por qué nunca se activa mi skill?

Porque su description indica lo que hace el skill, pero no cuándo se debe usar. Esa línea es todo lo 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. Se usa cuando el usuario solicita 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 se produce cuando el skill se activa constantemente. Una descripción como «Se usa para cualquier cambio de código en este repositorio» coincide con todo. Por tanto, el contenido se carga en cada tarea y permanece en el contexto durante el resto de la sesión. Restrinja la descripción al caso que quería cubrir. En Claude Code también puede establecer disable-model-invocation: true en el frontmatter. Esto impide la carga automática y mantiene el skill disponible cuando escribe su nombre.

El tercer fallo se produce cuando el skill 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 cuando el harness ya tiene una herramienta de búsqueda, proporcionan una ruta más lenta y dos conjuntos de instrucciones que pueden contradecirse. 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 el skill 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. Esto 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 activarlo, 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 lanzó 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 que observa cómo realiza una tarea una vez, la reconstruye como una intención con pasos ordenados y escribe el resultado como una skill. Que un proveedor cree un grabador cuyo formato de salida pertenece a la especificación de otra empresa es una buena señal de que el formato ha dejado de ser una función exclusiva de un producto.

Qué escribir primero

No planifique una biblioteca. Espere hasta que se sorprenda pegando las mismas instrucciones en un chat por tercera vez. Después, mueva ese texto a un SKILL.md y elimine el texto pegado. La repetición que ya ha experimentado es el único indicador fiable de que una habilidad merece conservarse. 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 estructurarse.

Dos hábitos mantienen la biblioteca en buen estado. Lea todas las habilidades que no haya escrito usted 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 y se comparte. Mantener los secretos alejados de sus agentes explica dónde deben almacenarse esos valores, y la hoja de ruta para aprender sobre agentes este año coloca las habilidades en el orden adecuado 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, se utilicen o no. Una habilidad de agente es una carpeta que contiene un archivo SKILL.md. No incluye ningún proceso ni protocolo 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 indicar al agente el procedimiento correcto para utilizar ese acceso. Muchas configuraciones usan 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 se puede transferir entre ellos sin cambios.

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

La limitación es el presupuesto de inicio, no el número de habilidades. Cada habilidad instalada aporta su nombre y descripción, unos 100 tokens según las indicaciones publicadas en la especificación. Por tanto, treinta habilidades consumen alrededor de 3,000 tokens antes de utilizar ninguna. Lo primero que se degrada es la selección, no la velocidad: muchas habilidades con descripciones similares dificultan que el modelo elija la correcta. Escriba descripciones que no se solapen y elimine las habilidades que haya dejado de usar.

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

Compruebe si se aplica a todas las tareas del repositorio. Los comandos de compilación, el estilo del proyecto y las reglas de nomenclatura se aplican a todas ellas, por lo que deben estar en el archivo que se carga siempre. Ese es precisamente el objetivo de cargarlo en cada ejecución. Un procedimiento que se ejecuta ocasionalmente, como una lista de comprobación de una versión o un ejercicio 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 haya crecido hasta convertirse en una serie de pasos numerados suele ser una habilidad que debe trasladarse.