La descripción de una herramienta MCP es una frase pegada a una única función
invocable: qué hace, qué recibe, si cambia algo. Viaja con cada petición que el
cliente envía al modelo, junto a la descripción de todas las demás
herramientas. Una skill es una carpeta con un archivo SKILL.md dentro, que
guarda un procedimiento — haz esto, luego comprueba aquello, pregunta antes de
esa otra cosa — y su cuerpo solo se carga cuando el modelo decide que la
petición encaja con ella.
Esa es toda la distinción, y es una distinción sobre cuándo está el texto en contexto, no sobre lo que el texto dice. Las descripciones son el precio de la entrada: se pagan todas, en cada turno, para siempre. Las instrucciones de una skill son gratis mientras no sean relevantes. Por eso un párrafo indefendible en la descripción de una herramienta — trescientas palabras sobre cómo clasificar una pila de grabaciones de reuniones pendientes — resulta perfectamente razonable en una skill.
Este artículo trata de decidir cuál de sus instrucciones va a cada sitio. Si el protocolo en sí le resulta nuevo, qué es un servidor MCP presenta primero el vocabulario, y MCP frente a plugins e integraciones sitúa MCP respecto a las formas antiguas de conectar cosas.
En la especificación de MCP, la definición de una herramienta es una forma
pequeña y fija. Lleva un name, un title legible opcional, una description,
un inputSchema que describe los argumentos, un outputSchema opcional y
annotations: propiedades opcionales que describen el comportamiento de la
herramienta, por ejemplo si solo lee. El cliente recupera la lista completa con
una llamada tools/list y la pone delante del modelo, que es lo que hace que
las herramientas MCP estén controladas por el modelo: él elige una según la
conversación.
Esta forma es buena en exactamente una cosa: decirle al modelo qué hace una llamada concreta para que elija la correcta. Es estructuralmente mala en otras tres.
No puede describir un orden. Nada en la definición de una herramienta puede
decir «llama a list_channels antes que a share_to_channel, porque el canal
tiene que existir y el usuario tiene que elegirlo». Cada descripción es una
isla.
No puede contener mucho. Cada descripción está en contexto en cada petición de cada conversación, incluidas todas las que nunca tocarán esa herramienta. Un servidor con quince herramientas y un párrafo en cada una ha gastado una parte apreciable de la ventana de contexto antes de que el usuario escriba nada.
No puede codificar su criterio. «Etiqueta la grabación en vez de compartirla cuando no tengas claro quién debe verla» es una política, no la descripción de una función. Dos equipos distintos querrían dos políticas distintas de la misma herramienta.
El protocolo deja una válvula de escape: un servidor puede devolver una cadena
instructions cuando el cliente se conecta, y el cliente puede añadirla al
prompt de sistema, por delante de la lista de herramientas. Ese es el sitio
adecuado para una orientación breve: qué es este servidor, a qué está conectado,
con qué hay que tener cuidado. Dos matices. Sigue siendo texto por sesión, así
que conviene que sea corto. Y la especificación dice que los clientes pueden
usarla, no que deban hacerlo, de modo que mostrársela realmente al modelo es
algo que varía de un cliente a otro.
Una skill es un directorio que contiene un archivo SKILL.md: frontmatter YAML
con un name y una description, y después instrucciones en markdown. Puede
llevar otras cosas al lado — scripts/ para código ejecutable, references/
para documentación detallada, assets/ para plantillas — y el agente solo las
carga cuando las instrucciones le mandan allí.
El modelo de carga se llama divulgación progresiva, y la especificación lo desglosa en tres etapas:
name y la
description de cada skill disponible, con un presupuesto de unos 100 tokens
por skill. Lo justo para saber cuándo podría ser relevante, y nada más.SKILL.md. La recomendación es no pasar de
unos 5000 tokens, y de 500 líneas en el archivo principal.Así que el coste de tener veinte skills instaladas son veinte descripciones cortas. El coste de tener veinte descripciones de herramienta largas son veinte descripciones largas, en cada turno. Esa asimetría es la razón de ser de la capa.
El formato no depende del cliente. Agent Skills lo desarrolló Anthropic y se
publicó como estándar abierto en agentskills.io; el escaparate de clientes que
hay allí enumera decenas de productos que leen la misma carpeta, entre ellos
Claude Code, Claude, ChatGPT y Codex, Cursor, VS Code, GitHub Copilot, Gemini
CLI, Goose, Roo Code, Kiro, Junie, Amp, Factory, Tabnine, Snowflake Cortex Code
y Databricks Genie Code. Comprobado el 14 de agosto de 2026.
El frontmatter obligatorio es deliberadamente escueto. name admite hasta 64
caracteres —minúsculas, dígitos y guiones— y debe coincidir con el nombre del
directorio padre. description admite hasta 1024 caracteres y debería decir
tanto qué hace la skill como cuándo usarla, porque esa cadena es la única base
sobre la que un agente decide si abre el archivo. Los campos opcionales son
license, compatibility, metadata y el experimental allowed-tools.
Ese campo de descripción merece más cuidado del que se le da. «Ayuda con las notas de reuniones» no encajará nunca de forma fiable; «revisa y clasifica las grabaciones recientes: las etiqueta, nombra a los participantes y comparte las que pertenecen a un canal de equipo; úsala cuando el usuario pida ordenar, clasificar o ponerse al día» sí.
Entre las descripciones por llamada y las skills bajo demanda hay una capa que no es ninguna de las dos: archivos que un agente lee al empezar una sesión, sea cual sea lo que usted haya pedido.
AGENTS.md es la versión más sencilla: markdown estándar, sin campos obligatorios, leído desde el archivo más cercano subiendo por el árbol de directorios. Su propio sitio declara uso en más de 60 000 proyectos de código abierto y lista compatibilidad con OpenAI Codex, Google Jules y Gemini CLI, los agentes de Claude, el agente de programación de GitHub Copilot, Aider, VS Code, Cursor, Zed, Warp, Factory, goose, Roo Code, Devin y Junie. Comprobado el 14 de agosto de 2026.
Las reglas de Cursor son la misma idea con un interruptor. Viven en
.cursor/rules como archivos .mdc, y tres campos del frontmatter deciden
cuándo se incluye cada una: alwaysApply: true la mete en todas las sesiones de
chat; una description deja que el agente juzgue la relevancia; globs la
activa cuando hay abierto un archivo que coincide; y sin ninguno de ellos, la
regla solo llega si la menciona con @. Cursor también admite AGENTS.md y
ahora admite Agent Skills directamente —las skills viven en .cursor/skills/ o
.agents/skills/— con una herramienta de migración que convierte en skills las
reglas dinámicas y los comandos de barra que reúnen los requisitos. Comprobado
el 14 de agosto de 2026.
Relea esos dos párrafos y el patrón queda claro: los formatos han convergido;
los modelos de carga, no. Todo el mundo lee ya SKILL.md. Pero una regla
alwaysApply y un bloque de AGENTS.md tienen alcance de sesión, y una skill
tiene alcance de tarea, y ninguna compatibilidad de formato cambia eso.
La consecuencia práctica es una regla general que vale más que los detalles de formato:
| Dónde va | Qué corresponde ahí | Qué cuesta |
|---|---|---|
description de la herramienta |
Una frase: qué hace esta llamada y qué cambia | Cada petición, siempre |
instructions del servidor |
Una orientación breve sobre todo el servidor | Cada sesión con ese servidor |
AGENTS.md, reglas siempre activas |
Hechos ciertos para cualquier tarea de este repositorio | Cada sesión de este proyecto |
SKILL.md |
Procedimientos, políticas, ejemplos resueltos, criterio | Solo cuando la tarea encaja |
Todo lo largo, todo lo condicional, todo lo que solo es cierto a veces: skill.
El fallo típico es meter ciento cincuenta líneas de procedimiento propio de un
producto en un AGENTS.md global, donde se quedan en contexto mientras se
trabaja toda la tarde en un backend que no tiene nada que ver.
Speak-Y trae un servidor MCP, y es una ilustración decente porque ahí se ven las dos capas haciendo trabajos distintos.
Las descripciones de herramientas cubren las llamadas: buscar grabaciones, leer
una transcripción, un resumen o los puntos de acción, listar canales y etiquetas
y, con la aplicación en marcha, etiquetar una grabación, renombrar a un
participante, cambiarle el título, volver a transcribirla o archivarla en un
canal de equipo. Cada una lleva una anotación que dice si lee o si cambia algo,
que es lo que permite a un cliente preguntar antes de ejecutar las que cambian,
y lo que convierte --read-only en un único interruptor en vez de una lista de
nombres de herramientas que recordar. La lectura ocurre localmente contra la
biblioteca de su equipo; los comandos que cambian algo pasan por la aplicación
en marcha y quedan registrados allí, como detalla
qué hace seguro el acceso de escritura de MCP.
La skill cubre el trabajo. Cuando instala la integración desde
Configuración → Integraciones, Speak-Y escribe una skill organizadora junto
a la configuración del servidor: por dónde empezar al clasificar una pila de
grabaciones, cuándo la respuesta correcta es una etiqueta y cuándo un canal, qué
acciones confirmar antes de ejecutarlas. Las descripciones no podrían contener
eso, y la cadena instructions del servidor no debería intentarlo.
Además está escrita como premia el modelo de carga. Un archivo detallado vive en
un solo sitio, y cada cliente recibe un puntero corto hacia él en el formato que
ese cliente lee: un SKILL.md para Claude Code, una regla .mdc para Cursor,
un bloque marcado dentro de AGENTS.md para Codex, un bloque marcado en
GEMINI.md para Gemini CLI. Los clientes con alcance de sesión reciben un
puntero precisamente por eso: ciento cincuenta líneas sobre notas de reuniones
no deberían estar residentes mientras usted depura el backend de otra persona.
Los bloques van entre marcadores, así que reinstalar sustituye solo esa sección
y deja el resto del archivo intacto.
El servidor MCP en sí es gratuito en todos los planes, incluido Free. La instalación en un clic y la configuración manual para cada cliente están documentadas en Asistentes de IA (MCP).
Tres preguntas, en orden.
¿La instrucción describe una sola llamada? Entonces es la descripción de una herramienta, y debería ocupar una o dos frases. Si se descubre escribiendo una tercera, ha encontrado una skill.
¿Es cierto en todas las sesiones, sea cual sea la tarea? Entonces puede ir
en AGENTS.md o en una regla siempre activa, pero revise con honestidad la
parte de «sea cual sea la tarea». «Este repositorio usa pnpm» cumple. «Este es
nuestro proceso de clasificación de reuniones», no.
¿Describe un procedimiento con pasos, elecciones o excepciones? Skill.
Someta el nombre y la descripción a un examen serio, porque esas dos cadenas
hacen todo el enrutado, y ponga lo largo en un archivo de references/ junto al
SKILL.md en vez de dentro.
Si se equivoca por el lado barato, su agente tendrá un contexto inflado y peor acierto en cualquier pregunta ajena. Si se equivoca por el lado caro —el procedimiento embutido en las descripciones de herramientas—, el modelo leerá su política en cada turno y aun así puede que no la siga, porque una descripción se lee como documentación de una función, no como una orden que cumplir.
Si quiere ver la diferencia en concreto, la prueba más rápida es escribir una skill para un trabajo que de verdad repite y compararla con los prompts que pegaba antes. Prompts para preguntarle a la IA sobre sus reuniones es una buena fuente de candidatos: los que ejecuta más de dos veces son los que merecen un archivo.
Una descripción es una frase pegada a una única función invocable, escrita por el autor del servidor y enviada al modelo en cada petición como parte de la lista de herramientas. Una skill es una carpeta con un archivo SKILL.md que contiene un procedimiento: varios pasos, varias herramientas, decisiones de criterio; y solo su nombre y su descripción están en contexto hasta que el modelo decide que la tarea encaja. Las descripciones responden a «qué hace esta llamada»; las skills, a «cómo se hace este trabajo».
No para tareas de una sola llamada. Hace falta cuando un trabajo requiere varias herramientas en un orden concreto, cuando elegir bien entre dos herramientas depende de un contexto que las descripciones no pueden llevar, o cuando quiere que el mismo procedimiento se repita igual en todas las sesiones. Las buenas descripciones hacen correcta cada llamada; una skill hace consistente una secuencia de llamadas.
No. Agent Skills lo desarrolló Anthropic y se publicó como estándar abierto en agentskills.io, y el escaparate de clientes de ese sitio enumera decenas de productos que lo han adoptado, entre ellos Claude Code, ChatGPT y Codex, Cursor, VS Code, GitHub Copilot, Gemini CLI, Goose, Roo Code, Kiro, Junie y Factory. Comprobado el 14 de agosto de 2026.
AGENTS.md es markdown simple, sin campos obligatorios, que el agente lee desde el directorio más cercano del árbol, y se carga para toda la sesión sea cual sea lo que usted haya pedido. El cuerpo de una skill se carga solo después de que el agente compare su petición con la descripción. Ambos son útiles, pero todo lo que sea largo pertenece a una skill, porque el contenido de AGENTS.md ocupa contexto en todas las sesiones, incluidas las que no tienen nada que ver con él.
La especificación de Agent Skills recomienda mantener el SKILL.md principal por debajo de 500 líneas y de unos 5000 tokens, y mover el material de referencia detallado a archivos aparte que el agente cargue solo cuando los necesite. El nombre y la descripción tienen un presupuesto de unos 100 tokens, porque son lo que paga cada sesión.