← Base de Conocimientos

Archivo de skill (SKILL.md)

¿Qué es SKILL.md?

SKILL.md es un único archivo Markdown — habitualmente servido en /skill.md — que indica a un agente de IA cómo usar tu servicio. El archivo abre con frontmatter YAML que declara dos campos, name y description, seguido de Markdown libre que documenta los endpoints, el modelo de autenticación y la forma de las peticiones que el agente necesita para actuar.

La especificación se publica en agentskills.io y ha sido adoptada como convención multi-proveedor por Claude Code de Anthropic, OpenAI Codex, Cursor, GitHub Copilot y el Agent Framework de Microsoft. Un archivo SKILL.md es el artefacto más pequeño posible que permite a un agente pasar de "he encontrado este sitio" a "sé cómo llamarlo."

Por qué importa SKILL.md

Los agentes LLM enfrentan el mismo coste de onboarding que los humanos: averiguar para qué sirve un servicio desconocido y cómo invocarlo correctamente. Con humanos escribes una guía de inicio rápido; con agentes escribes un SKILL.md. El name del frontmatter da al agente un identificador estable que puede registrar internamente; la description es lo que aparece en los listados de herramientas y en el planificador del agente; el cuerpo es el manual de juego.

La alternativa — un agente leyendo tu sitio de documentación completo, esquema OpenAPI y página principal para reconstruir la misma información — es lenta, cara y con pérdidas. SKILL.md reduce el paso de onboarding a un único fetch y unos pocos cientos de tokens. Para sitios que quieren que los agentes los usen de verdad (no solo los descubran), SKILL.md es el archivo de mayor apalancamiento que puedes publicar.

Cómo funciona SKILL.md

No hay handshake de protocolo. Un agente solicita /skill.md, parsea el frontmatter YAML buscando name y description, valida el nombre contra la regex de la especificación y lee el cuerpo Markdown como instrucciones.

Un SKILL.md mínimo válido:

---
name: scan-url
description: Escanea cualquier URL para evaluar la agent-readiness y devolver una puntuación de 0 a 100. Úsalo cuando el usuario pregunte qué tan agent-ready es un sitio o quiera comparar soporte de protocolos entre sitios.
---

# Escaneo de Agent Readiness

Usa `GET /api/v1/scan?url={url}` para la respuesta JSON amigable para agentes.

## Endpoints

- `GET /api/v1/scan?url={url}` — JSON plano para agentes
- `GET /api/scan?url={url}` — informe HTML completo (para humanos)
- `GET /api/badge?url={url}` — badge SVG

## Auth

Ninguna. Todos los endpoints son gratuitos.

## Ejemplo

`curl https://agentgrade.com/api/v1/scan?url=https://example.com`

Esa es toda la superficie. Los agentes que encuentren este archivo saben lo suficiente para llamar tu servicio correctamente al primer intento.

SKILL.md vs otros archivos de agent-readability

Archivo	Quién lo sirve	Qué responde	Formato
SKILL.md	El servicio	¿Cómo uso este servicio?	Markdown + frontmatter
OpenAPI	El servicio	¿Qué endpoints existen y cuál es el schema?	JSON/YAML
Manifiesto MCP	El servidor MCP	¿Qué herramientas expone este servidor sobre JSON-RPC?	JSON-RPC
ai-plugin.json	El servicio	Metadata de plugin para el formato legacy de plugins de ChatGPT	JSON
llms.txt	El servicio	¿Qué es este sitio, en prosa?	Markdown

SKILL.md es la capa "manual de juego"; OpenAPI es la capa "esquema". Las dos se componen: SKILL.md dice al agente qué endpoints llamar y cuándo; OpenAPI proporciona el schema formal de parámetros. Los agentes que encuentran ambos están estrictamente mejor que los que encuentran solo uno.

ai-plugin.json predataba SKILL.md y estaba atado al formato original de plugins de ChatGPT, que OpenAI ha deprecado. SKILL.md es el sucesor moderno y multi-proveedor.

Validación de frontmatter

La especificación de agentskills.io es estricta con dos campos:

• name — de 1 a 64 caracteres, alfanumérico minúscula con guiones simples. Debe coincidir con ^[a-z0-9]+(-[a-z0-9]+)*$. Sin guiones iniciales, finales o consecutivos. Bien: scan-url, book-flight. Mal: ScanUrl, -scan, scan--url, scan_url.
• description — de 1 a 1024 caracteres. Empieza con el verbo que el agente debe ejecutar. La descripción aparece en selectores de herramientas y razonamiento del planificador.

Los agentes y escáneres que cumplen la especificación rechazan archivos con frontmatter mal formado — tu archivo se vuelve efectivamente invisible.

Quién ha adoptado SKILL.md

La especificación pasó de convención de un solo proveedor a estándar interoperable durante 2025:

• Claude Code (docs.claude.com/en/docs/claude-code/skills) — el agente de coding de Anthropic carga archivos SKILL.md desde directorios locales.
• OpenAI Codex — Adoptó el mismo formato para definiciones de skills de agente.
• Cursor — Lee SKILL.md desde workspaces de proyecto para guía inline del agente.
• GitHub Copilot — Honra la misma convención de frontmatter para instrucciones de agente a nivel de repo.
• Microsoft Agent Framework — Las implementaciones multi-proveedor siguen la especificación de agentskills.io.

Como el formato es Markdown con frontmatter YAML, el coste de adopción es casi nulo.

Cómo añadir SKILL.md a tu sitio

1. Elige el nombre. Una frase verbo-sustantivo, minúscula-guiones, menos de 64 caracteres. Coincide con lo que el agente debe "hacer" con tu servicio.
2. Escribe la descripción. Dos frases. Frase 1: qué consigue el agente. Frase 2: cuándo usarlo (la frase trigger o contexto).
3. Escribe el cuerpo. Endpoints con verbos HTTP, modelo de auth, un ejemplo curl copiable-pegable. Mantenlo por debajo de una pantalla de texto.
4. Sirve en /skill.md. Archivo estático. Content-Type: text/markdown.
5. Enlaza desde llms.txt o /.well-known/. Opcional pero recomendado.

Un sitio con SKILL.md válido y un esquema OpenAPI está bien equipado para cualquier agente que llegue sin saber nada.

Errores comunes que detectan los escáneres

• Faltan delimitadores de frontmatter — el archivo no empieza con ---.
• name inválido — mayúsculas, guiones bajos o guiones iniciales/finales. El fallo más común.
• Descripción demasiado corta — bajo 1 carácter (vacía) o tan corta que el agente no tiene señal. Apunta a 80-200 caracteres.
• Descripción demasiado larga — sobre 1024 caracteres. Mueve detalle al cuerpo.
• Ruta equivocada — servido en /skills.md (plural), /.well-known/skill.md o /skill/index.md. La especificación es /skill.md en la raíz del documento.
• Content-type equivocado — servido como text/html porque un CMS auto-renderiza el Markdown. Sirve text/markdown o text/plain en crudo.

FAQ

¿SKILL.md es lo mismo que las "Claude Skills" de Anthropic?

El formato en disco es el mismo. "Claude Skills" es el nombre del producto de Anthropic para la funcionalidad que consume archivos SKILL.md; el formato es la especificación multi-proveedor de agentskills.io.

¿Necesito tanto SKILL.md como OpenAPI?

Envía ambos si tienes una API. SKILL.md responde "¿cómo lo uso?" en prosa; OpenAPI responde "¿cuál es el esquema exacto?" formalmente.

¿Qué reemplazó a /skills.json?

/skills.json era un formato de manifiesto temprano, hecho a mano, anterior a cualquier estándar. Fue superado por SKILL.md para la capa "cómo usar" y por el x-payment-info de OpenAPI (ver OpenAPI) para declarar endpoints pagados. AgentGrade ya no puntúa /skills.json.

¿Dónde debe vivir el archivo SKILL.md?

/skill.md en la raíz del documento. Algunos agentes también sondean /.well-known/skill.md como fallback.

¿Puede un sitio tener múltiples archivos SKILL.md?

La convención es un /skill.md por origen. Servicios con múltiples superficies distintas típicamente describen cada una como sección dentro de un archivo.

¿SKILL.md reemplaza a MCP?

No — responden preguntas distintas. SKILL.md dice a un agente cómo usar tu servicio HTTP vía endpoints existentes. MCP define una interfaz JSON-RPC donde el agente llama a tu servidor como herramienta sobre una conexión persistente.

¿AgentGrade penaliza sitios que publican SKILL.md sin OpenAPI?

No. SKILL.md es una señal positiva por sí solo.

¿Los agentes leerán realmente este archivo?

Claude Code, Codex, Cursor y Copilot leen archivos SKILL.md en sus workspaces hoy. Los agentes navegadores prueban cada vez más /skill.md como parte del handshake de descubrimiento.

Madurez de la especificación

Estándar multi-proveedor. Definido en agentskills.io. Adoptado por Claude Code, OpenAI Codex, Cursor, GitHub Copilot y Microsoft Agent Framework.

Saber más

• agentskills.io — la especificación
• Documentación de Claude Code skills — la adopción de Anthropic
• OpenAPI — capa de schema acompañante
• MCP — alternativa para servidores de herramientas JSON-RPC

Relacionado: ¿Qué es la preparación para agentes de IA?