Saltar al contenido principal

SKILL.md - Agent Skills

¿Qué es una Skill?​

Una Skill es un formato y un estándar abierto diseñado para empaquetar e impartir conocimiento procedimental reutilizable a un agente de IA. Físicamente, consiste en una carpeta o directorio en el sistema de archivos que contiene, al menos, un archivo central de instrucciones llamado SKILL.md.

Su propósito es "enseñar" al agente cómo realizar de manera experta una tarea específica y repetible, sin necesidad de reentrenar el modelo.

🎧 Podcast: Agent Skills

Beneficios Principales​

  • Ahorro extremo de contexto (economía de tokens): a diferencia de las reglas globales (como AGENTS.md) que se envían en cada turno de chat, las Skills sólo se cargan en la memoria de trabajo del modelo cuando la tarea lo requiere.
  • Portabilidad y estándar abierto: al ser una especificación abierta de la comunidad de IA, una Skill escrita bajo este estándar puede ser leída e interpretada de forma transparente por diversos agentes de desarrollo (como Claude Code, OpenCode o Cursor).
  • Especialización modular: pPermite estructurar automatizaciones complejas (como generar notas de lanzamiento o validar bases de datos) siguiendo principios de ingeniería de software: responsabilidad única, bajo acoplamiento y fácil mantenimiento.

Formato y Estándar (Estructura de Directorios)​

El estándar define que una Skill es un paquete autónomo estructurado de la siguiente forma:

nombre-de-la-skill/
├── SKILL.md          # REQUERIDO: Metadatos (YAML) e instrucciones de la tarea (Markdown)
├── scripts/          # OPCIONAL: Código ejecutable que el agente puede correr (Python, Bash, JS)
├── references/       # OPCIONAL: Documentación adicional de soporte
└── assets/           # OPCIONAL: Plantillas, recursos estáticos o datasets

Anatomía del archivo SKILL.md​

Este archivo se divide estrictamente en dos partes:

  1. YAML Frontmatter (Metadatos): Contiene los parámetros de control para el arnés y el agente.
    • name (Requerido): Máximo 64 caracteres. Solo admite minúsculas, números y guiones.
    • description (Requerido): Máximo 1024 caracteres. Es el campo más importante, ya que describe qué hace la Skill y cuándo debe activarse (es la firma que el modelo evalúa para disparar la habilidad).
    • Campos opcionales: license, compatibility, metadata y allowed-tools.
  2. Cuerpo Markdown (Instrucciones): Contiene las directrices paso a paso, ejemplos de entrada/salida y checklists de validación que el agente debe seguir de forma estricta.

Ejemplo mínimo

SKILL.md
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---
Skill body description in markdown format.
....

¿Cómo las procesan los LLM? (carga por etapas)​

Para evitar saturar la ventana de contexto de la IA, el arnés de ejecución del agente procesa las Skills utilizando un mecanismo llamado revelación progresiva (progressive disclosure) en tres niveles:

Nivel 1: Metadatos (Nombre + Descripción)
   └── Se cargan siempre al iniciar la sesión (~100 tokens por Skill)

Nivel 2: Cuerpo de SKILL.md (Instrucciones)
   └── Se carga en el contexto sólo si la Skill es activada (< 5,000 tokens)

Nivel 3: Recursos (scripts/ y references/)
   └── Se leen o ejecutan bajo demanda, sólo si el procedimiento los invoca
Detalle de niveles
Nivel 1 (Filtro inicial): Al arrancar la sesión, el agente lee únicamente el nombre y la descripción de todas las Skills instaladas. Esto consume apenas 100 tokens por Skill, lo que permite tener decenas de habilidades en un proyecto sin coste de contexto.
Nivel 2 (Activación): Cuando el modelo decide que la tarea actual requiere la Skill, lee el archivo SKILL.md desde el disco local. El cuerpo de la instrucción entra entonces en la ventana de contexto (se recomienda mantenerlo por debajo de 500 líneas o 5000 tokens).
Nivel 3 (Ejecución de recursos): Si el cuerpo de la Skill hace referencia a un script (ej. un validador en Python) o a un archivo de convenciones, el agente los lee o ejecuta sólo en el momento en que los necesita. Esto ahorra tokens y evita inyectar ruido innecesario.

Métodos de Activación​

Un agente puede invocar e integrar una Skill en su flujo de razonamiento mediante dos vías:

  1. Invocación automática (Probabilística): El modelo de lenguaje analiza tu petición en lenguaje natural. Si detecta un patrón semántico que coincide con la descripción configurada en el frontmatter de una Skill, la activa de forma autónoma.
  2. Invocación explícita (Determinista): El usuario fuerza la ejecución directa de la habilidad llamándola por su nombre, típicamente usando un comando de terminal o comando de barra diagonal (por ejemplo, /pre-commit-check o /release-notes).

Resumen​

Actualmente, el uso de Skills está ampliamente extendido en la industria y la mayoría de los agentes de código soportan su carga. Es recomendable visitar los distintos catálgos disponibles y aprovechar las skills oficiales de proveedores y referentes.

Última actualización en