Qué son realmente las habilidades de un agente

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 iniciar y lee las instrucciones sólo cuando la solicitud coincide con esa descripción o cuando se invoca la habilidad por su nombre. 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 contiene un SKILL.md ya 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 subestima. 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 casi no cuesta nada 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 name y description de cada skill instalada, y nada más. La especificación de Agent Skills estima ese contenido en unos 100 tokens por skill (orientación publicada a fecha de octubre de 2026). Si instala una docena de skills, habrá utilizado aproximadamente el contexto de un párrafo largo.

Cuando una solicitud coincide con una descripción, el agente lee el contenido de ese único 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/ todavía no tienen ningún coste en este punto. Un archivo de referencia sólo se carga si las instrucciones indican al agente que debe consultarlo. Un script incluido funciona de otra manera: 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 lo primero que suele utilizar la gente: 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 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 todo el argumento 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 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, 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 a una función, es algo que el modelo puede invocar. El entorno de ejecución proporciona un esquema al modelo: 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 realizan acciones. Las dos partes de ese intercambio pertenecen a el entorno de ejecución, el programa que ejecuta el bucle alrededor del modelo, que también es el componente que lee las descripciones de las skills al iniciar y decide cuándo abrir una.

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. Delegar un trabajo a un segundo agente es el ejemplo más claro: una sesión de Claude Code ya puede enviar mensajes a otra, y la skill es el lugar donde se documenta cuándo merece la pena hacerlo y qué se debe enviar.

En resumen: una herramienta proporciona al agente una capacidad nueva, mientras que una skill principalmente le proporciona criterio para usar capacidades que ya tiene. Cuando una skill añade una capacidad, lo hace mediante un script incluido que el agente ejecuta con el shell que ya tenía. Si un paso debe producir siempre un resultado exacto y validado, se necesita una herramienta o un script. Si un paso requiere aplicar el mismo razonamiento de forma coherente, se necesita una skill. Una skill puede consistir únicamente en criterio y, aun así, ser la que se usa con más frecuencia, como muestra Ponytail, que hace que un agente de programación realice el cambio mínimo que funciona: no añade ninguna capacidad nueva y sólo cambia la forma en que el agente utiliza las que ya tiene. Ese criterio también puede orientarse en sentido contrario, y la skill unlazy, que recorre un Depth Tree para evitar que un agente declare terminado un trabajo antes de tiempo aplica la misma técnica a la exhaustividad en lugar de a la moderación.

Una 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, utiliza ese protocolo y expone herramientas al agente. Normalmente necesita configuración, credenciales y un comando local o un endpoint de red. Una 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. En un cliente que las carga de antemano, estos elementos permanecen en la solicitud durante toda la sesión, se utilicen o no. Claude Code ya no funciona así de forma predeterminada: desde octubre de 2026, su búsqueda de herramientas está activada desde el inicio, por lo que al comenzar la sesión sólo se cargan los nombres de las herramientas y las instrucciones del servidor. Las definiciones completas se cargan cuando Claude las busca. Una skill almacenada ocupa una línea de texto.

Las dos opciones se complementan, y las configuraciones más eficaces utilizan ambas. El servidor MCP proporciona el acceso. La skill proporciona el procedimiento: qué herramientas de esas se deben llamar para el flujo de trabajo real del equipo, en qué orden y cómo debe ser un resultado correcto. Si aloja sus propios servidores, ejecutar servidores MCP en un VPS cubre esa parte.

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

Ambas son instrucciones en Markdown, por lo que esta confusión es comprensible. La diferencia está en cuándo se cargan. AGENTS.md, CLAUDE.md y el prompt del sistema están siempre activos. Una skill se activa bajo demanda. Los estilos de salida de Claude Code están en el extremo de lo que siempre está activo, porque elegir uno modifica el propio prompt del sistema. Por eso afecta a todas las respuestas de la sesión, incluidas aquellas en las que no interviene ninguna skill.

La prueba consiste en una pregunta: ¿sería incorrecto ignorar este párrafo en una tarea que no tiene ninguna relación con él? Las reglas sobre el estilo del proyecto, el comando de compilación y la nomenclatura de ramas se aplican a todas las tareas, por lo que deben estar en el archivo siempre activo. Que se cargue cada vez es precisamente la finalidad de ese archivo. La lista de comprobación de versiones que 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 trasladarla.

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

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 confirman en 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 proyecto desde .github/skills/ y .agents/skills/, además de .claude/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.

Eso es una skill completa. El nombre del directorio se convierte en el comando que se escribe, 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 el archivo se ha detectado. Si no aparece en ese menú, compruebe primero los nombres: el archivo debe llamarse SKILL.md, y la especificación Agent Skills exige que el nombre use letras minúsculas, dígitos y guiones simples, y que coincida con el directorio. El mismo procedimiento, escrito de forma que el agente pueda volver a ejecutarlo, complementa de forma natural las copias de seguridad programadas con 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.

Primero, el código fuente de un script no 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 longitud cada vez que se carga la habilidad.

Segundo, 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 día con errores la aplicará de forma ligeramente distinta. El problema no se detectará hasta que dos cifras no coincidan.

Por tanto, separe el trabajo según su naturaleza. «Analizar el CSV e imprimir cada fila cuyo total no coincida con los elementos de línea» es un script. «Revisar las filas que ha impreso 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 sigue el mismo principio que crear un bucle que un agente pueda ejecutar sin supervisión.

¿Por qué mi skill nunca se activa?

Porque su description explica qué hace el skill, pero nunca indica cuándo debe usarse. Esa única 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. Úsalo cuando el usuario pida 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 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 tenía previsto. 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 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 entorno ya tiene una herramienta de búsqueda, crean un proceso más lento y dos conjuntos de instrucciones que pueden entrar en conflicto. Elimine el duplicado 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, lo que oculta las carencias de la versión escrita. El plugin skill-creator de Anthropic automatiza esa 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. Si el skill se carga y el agente sigue sin hacer lo que indica, el problema no está en la descripción. Consulte a continuación las razones por las que un agente ignora instrucciones que ya ha leído.

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

Anthropic publicó el formato a finales de 2025 y después lo convirtió en un estándar abierto alojado en agentskills.io. En octubre 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, de modo 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 con 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 cuya salida usa el formato definido por 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 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 desencadenante fiable de una habilidad que merezca 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 la estructura.

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 el 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 sitúa 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 sus definiciones completas de herramientas ocupan contexto durante toda la sesión, a menos que el cliente las difiera, como hace ahora Claude Code de forma predeterminada. Una habilidad de agente es una carpeta que contiene un archivo SKILL.md. No utiliza ningún proceso ni protocolo y consume alrededor de 100 tokens hasta que el agente decide leerla. Use un servidor MCP para dar a un agente acceso a un sistema. 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/, .claude/skills/ o .agents/skills/ en el repositorio. El archivo SKILL.md se puede trasladar entre ellos sin modificaciones.

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

La limitación está en el presupuesto de inicio, no en una cantidad concreta. Cada habilidad instalada aporta su nombre y su descripción, aproximadamente 100 tokens según las indicaciones publicadas en la especificación. Por tanto, treinta habilidades consumen unos 3,000 tokens antes de que se utilice 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 usar.

¿Esta instrucción debe ir 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 nomenclatura se aplican a todas ellas. Por tanto, deben estar en el archivo que se carga siempre, ya que su objetivo es cargarse en cada ocasión. Un procedimiento que se ejecuta ocasionalmente, como una lista de comprobación de una versión o un ejercicio de restauración, debe ser una habilidad. Así sólo añade su descripción de una línea en las tareas que no la necesitan. Una sección de AGENTS.md que ha crecido hasta convertirse en una serie de pasos numerados suele ser una habilidad pendiente de trasladar.