Un archivo SKILL.md es un archivo Markdown con una breve cabecera YAML que enseña a un agente de IA cómo realizar una tarea específica. Se ubica en una carpeta, opcionalmente junto con scripts, documentación de referencia y plantillas, y el agente lo carga solo cuando la tarea lo requiere. Los archivos SKILL.md siguen la especificación abierta Agent Skills, por lo que una misma habilidad funciona en varios agentes de programación. Para los equipos de producto, un archivo SKILL.md es la nueva puerta de entrada: la forma en que un agente aprende a usar el producto correctamente. Para los equipos de seguridad, es un archivo de texto plano que modifica el comportamiento del agente y merece la misma revisión que el código.
¿Qué es un archivo SKILL.md? #
Los agentes de IA son capaces, pero genéricos. Saben escribir código y usar herramientas. Desconocen el proceso de implementación, las convenciones de la API y los tres parámetros que la interfaz de línea de comandos necesita para ejecutarse de forma segura en la integración continua. Hasta hace poco, la solución consistía en pegar toda esa información en una solicitud del sistema que se cargaba en cada sesión y competía con el trabajo real por el contexto.
Un archivo SKILL.md resuelve esto de manera diferente. Empaqueta una funcionalidad (desplegar este servicio, clasificar estos hallazgos, generar este informe) en una carpeta que el agente puede descubrir, leer cuando sea relevante e ignorar en caso contrario. El formato fue desarrollado por Anthropic y publicado como un proyecto abierto. standard, Especificación de habilidades del agentey desde entonces ha sido adoptada por un número creciente de agentes, incluidos OpenAI Codex, GitHub Copilot y Cursor.
Así pues, un equipo que pregunta qué es un archivo SKILL.md en realidad se está haciendo dos preguntas: ¿cómo enseñamos a los agentes a usar bien nuestras herramientas y cómo evitamos que se les enseñe algo incorrecto? ¿Qué es la seguridad basada en IA agente?
Significado de SKILL.md: Lo que realmente contiene el archivo. #
El significado de SKILL.md es más simple que la publicidad que lo rodea. Una skill es una carpeta con un archivo obligatorio:
El archivo SKILL.md en sí tiene dos partes: #
- Cuerpo rebajado. Las instrucciones: pasos, reglas, ejemplos e indicaciones sobre los archivos de apoyo que el agente debe abrir cuando los necesite.
- Encabezado YAML. Como mínimo un
nameydescriptionLa descripción es la línea más importante del archivo, porque es lo que el agente lee para decidir si la habilidad se aplica.
Lo que no contiene: credenciales, lógica empresarial que deba estar en el código o instrucciones que solo tengan sentido en una conversación.
Por qué los archivos SKILL.md se convirtieron en un standard #
Porque el contexto es finito. Cada token gastado en instrucciones que un agente no necesita es un token que no se gasta en la tarea. Las habilidades se cargan por capas, por lo que un agente puede tener docenas de ellas y prácticamente no gastar nada hasta que una sea relevante.
La portabilidad hizo el resto. Una habilidad escrita una sola vez se ejecuta en cualquier agente que implemente la especificación. Para una empresa de productos, esto cambia la economía del soporte de agentes: en lugar de una integración por asistente, se publica una sola habilidad.
Y los agentes se convirtieron en usuarios. Los desarrolladores piden cada vez más a un agente que “configure el escáner” o “arregle el escáner”. pipelineEn lugar de leer la documentación, si el agente aprende sobre tu producto a partir de una publicación obsoleta en un foro, lo utilizará incorrectamente. Un archivo SKILL.md te permite decidir qué aprende el agente.
Cómo funciona un archivo SKILL.md: divulgación progresiva #
En la práctica, comprender qué es un archivo SKILL.md significa saber qué carga el agente y cuándo, porque eso es lo que evita que docenas de habilidades del agente saturen la ventana de contexto.
| Fase | Lo que carga el agente | Cuando se carga |
|---|---|---|
| Descubrimiento: | El nombre y la descripción de la introducción, unas pocas docenas de fichas por habilidad. | Al iniciar, por cada habilidad instalada |
| Activación | El cuerpo completo del archivo SKILL.md: pasos, reglas y ejemplos. | Cuando una tarea coincide con la descripción |
| Ejecución | Scripts, documentos de referencia y recursos incluidos en la carpeta. | Solo cuando las instrucciones lo requieran. |
El principio de diseño es la divulgación progresiva: metadatos al inicio, instrucciones al activarse y recursos al ejecutarse. Por eso la descripción es tan importante. Una descripción vaga significa que la habilidad nunca se activa o se activa cuando no debería.
Cómo estructurar tu producto para agentes de IA
#
Trate las habilidades del agente como una superficie de producto, con el mismo cuidado que le dedica a la referencia de su API.
- Una habilidad por puesto de trabajo, no una habilidad por producto. “Configurar el escaneo en CI” y “clasificar los hallazgos” son habilidades distintas. Una sola habilidad que intenta abarcarlo todo se activa de forma impredecible y sobrecarga el contexto que carga.
- Escribe la descripción como un desencadenante. Explica qué hace la habilidad y cuándo usarla, con las palabras que los usuarios realmente escriben.
- Mantén el texto breve e imperativo. Pasos, guardrails y valores predeterminados. Mueva la profundidad a
references/De esta forma, se carga solo cuando es necesario. - Incluya el trabajo determinista en los scripts. Si un paso debe realizarse siempre de la misma manera (validar una configuración, formatear la salida), envíe un script en lugar de un texto que el modelo tenga que interpretar.
- Codifique la ruta segura. Indica lo que el agente nunca debe hacer: omitir la validación, deshabilitar las comprobaciones, usar credenciales de producción. Los agentes siguen las reglas explícitas mucho mejor que las implícitas.
- Versión y pruébala como si fuera código. Mantén las habilidades en un repositorio, revisa los cambios en pull requests y probarlas con tareas reales antes de su lanzamiento.
Si tu producto expone acciones, combina la habilidad con un servidor MCP. MCP le da al agente acceso a tus herramientas; la habilidad le enseña a usarlas correctamente. ¿Qué es el Protocolo de Contexto de Modelo (MCP)?
¿Qué no es un archivo SKILL.md? Términos relacionados
#
Estos conceptos se confunden, lo que enturbia tanto las conversaciones sobre diseño como las de revisión.
- AGENTES.md y CLAUDE.md Son archivos siempre activos: las convenciones de todo el repositorio se cargan en cada sesión. Las habilidades se cargan bajo demanda.
- Un servidor MCP Expone herramientas y datos. Un archivo SKILL.md contiene conocimientos y procedimientos. Se complementan entre sí.
- Un mensaje del sistema es una instrucción fija para una aplicación. Una habilidad es portátil y reutilizable entre agentes.
- Un archivo de reglas (como un archivo de reglas de cursor) controla el comportamiento de un asistente dentro de una sola herramienta. Mismo perfil de riesgo, portabilidad más limitada.
- llms.txt Ayuda a los modelos a leer tu documentación. Una habilidad le indica a un agente qué hacer con ella.
Son capas, no competidoras. Lo que tienen en común es que cada una es un texto plano que modifica el comportamiento de un agente de IA, y cada una suele revisarse como documentación.
Standards que dan forma al significado de riesgo de SKILL.md #
Juzgue una fuente por su estado de publicación, no por lo actual que parezca.
El riesgo está documentado, no es hipotético. MITRE ATLAS cataloga un ataque en el que instrucciones ocultas en un archivo de reglas llevan a un asistente a generar código con puerta trasera sin dejar rastro visible. Un archivo SKILL.md malicioso funciona de la misma manera, y una habilidad que agrupa scripts puede ejecutar código además de dar instrucciones. Instalar una habilidad de la comunidad conlleva el mismo nivel de confianza.cisión como si estuviera instalando un paquete. → ¿Qué es la inyección rápida?
De la definición al programa #
Saber qué es un archivo SKILL.md no te indica cuántos hay ya en tus repositorios, quién los añadió ni qué instrucciones dan a los agentes.
Esa brecha se cierra de forma predecible. Descubre todas las habilidades, archivos de reglas y configuraciones de MCP en tu código, incluso las que nadie ha declarado. Analízalas como artefactos de seguridad, no como documentación. Mantén el registro actualizado para que un auditor o un responsable de respuesta a incidentes pueda ver qué activos de agente existen y cómo se conectan.
Seguridad de IA de Xygeni crea ese registro desde tu código. Las habilidades se ubican junto con modelos, conjuntos de datos, puntos finales de inferencia, agentes, servidores MCP, indicaciones, guardrails y herramientas de codificación de IA en un inventario continuo de IA, cada una con una puntuación de riesgo, proveedor, tipo y ubicación exacta en el código. Xygeni analiza los archivos de habilidades, los archivos de reglas y las configuraciones de MCP como artefactos de seguridad y marca los maliciosos. El gráfico de IA muestra qué agente accede a qué herramienta, y se exporta un AI-BOM legible por máquina a partir del mismo descubrimiento. → ¿Qué es una lista de materiales de IA? y ¿Qué es Shadow AI?
Agenda una demo para ver las habilidades del agente que ya están en tu inventario de IA.
Preguntas Frecuentes #
Un archivo Markdown que enseña a un agente de IA cómo realizar una tarea específica, y que se carga solo cuando surge esa tarea.
En una carpeta por habilidad, normalmente dentro del repositorio del proyecto o del directorio de configuración del agente del usuario. La ubicación exacta depende del agente.
Sí, siempre que ambos cumplan con la especificación de Habilidades del Agente. El mismo archivo SKILL.md se ejecuta en cualquier agente compatible sin necesidad de modificaciones.
Si los desarrolladores utilizan agentes de IA para configurar u operar su producto, sí. Es la forma más directa de garantizar que los agentes lo utilicen de forma correcta y segura.
Pueden serlo. Una habilidad es una instrucción que el agente sigue y puede incluir scripts ejecutables. Revisa las habilidades como si fueran código, instala habilidades de la comunidad solo de fuentes confiables y mantén un inventario de las habilidades disponibles en tus repositorios.
