## ¿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](https://agentskills.io/specification) 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: ```markdown --- 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](/kb/es/openapi)** | El servicio | *¿Qué endpoints existen y cuál es el schema?* | JSON/YAML | | **Manifiesto [MCP](/kb/es/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](/kb/es/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](https://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](/kb/es/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](/kb/es/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](/kb/es/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](https://agentskills.io/specification). Adoptado por Claude Code, OpenAI Codex, Cursor, GitHub Copilot y Microsoft Agent Framework. ## Saber más - [agentskills.io](https://agentskills.io/specification) — la especificación - [Documentación de Claude Code skills](https://docs.claude.com/en/docs/claude-code/skills) — la adopción de Anthropic - [OpenAPI](/kb/es/openapi) — capa de schema acompañante - [MCP](/kb/es/mcp) — alternativa para servidores de herramientas JSON-RPC