Agent-Skills: un standard para que los asistentes AI actúen en tu sitio

Un draft standard para que los asistentes AI (ChatGPT, Claude, Perplexity, Gemini) puedan ejecutar capacidades en nombre de tu sitio — agendar una llamada, pedir cotización, contacto — leyendo un solo archivo Markdown en /.well-known/agent-skills/SKILL.md.

Agent-Skills: un standard para que los asistentes AI actúen en tu sitio

TL;DR: Cuando un usuario le pide a Claude "agenda una llamada de discovery con Acme", Claude tiene que crawlear el sitio, adivinar cómo funciona el formulario, y probablemente inventarse la mitad de los pasos. Construimos y abrimos agent-skills, un standard chiquito que lo resuelve con un solo archivo Markdown en /.well-known/agent-skills/<name>/SKILL.md. El archivo describe una capacidad en prosa que un LLM puede seguir literal. Es complementario a OpenAPI, MCP y Schema.org potentialAction — ninguno de ellos describe cuándo invocar una capacidad, qué preguntarle al usuario primero, o qué decirle sobre las expectativas. El repo tiene el draft v0.1 del spec (CC BY 4.0), tres ejemplos production-grade, y un validator + CLI con cero dependencias (MIT). Está desplegado en dualnova.org hoy y funciona.

El problema que nos seguía golpeando

Empezamos a ver la misma conversación repetirse, semana tras semana, en nuestras entrevistas de customer-discovery:

Founder: "Le pedí a ChatGPT ayer que me agendara una llamada con ustedes." Nosotros: "Genial — ¿funcionó?" Founder: "Bueno, me dio un número de teléfono. No estoy seguro de dónde lo sacó. Mejor les escribí un email."

El número estaba mal. ChatGPT lo había alucinado de una empresa de nombre parecido.

Multiplica esto por cada founder preguntándole a cada asistente AI cómo contactar a cualquier empresa B2B chica. El state of the art actual es: el asistente lee el HTML, intenta encontrar un formulario de contacto o un email, frecuentemente se equivoca, y le entrega al usuario una respuesta confidentemente equivocada.

Las dos opciones existentes para arreglar esto tienen problemas reales:

1. OpenAPI. Excelente para integración de backend pero completamente silenciosa sobre la capa user-facing. Una spec de OpenAPI le dice a un LLM que el endpoint existe y qué fields acepta. No le dice cuándo debería llamarlo ("solo cuando el usuario explícitamente quiere una llamada"), qué preguntar primero ("nombre, email, descripción del proyecto, idioma preferido"), o qué decirle al usuario sobre expectativas ("30 minutos, gratis, video call, confirmación en 1 minuto").

2. MCP (Model Context Protocol). Excelente para agentes tightly-coupled como Claude Desktop, IDEs, o n8n donde el usuario conectó activamente el server. Heavyweight para una capacidad pública one-off — ningún website va a levantar un MCP server solo para que ChatGPT pueda agendar una llamada. El ceiling de despliegue es muy alto.

Hay un middle faltante: recetas de acción descubribles públicamente, basadas en prosa que cualquier LLM pueda fetchear y seguir sin setup.

Agent-skills en 60 segundos

Un sitio publica uno o más archivos SKILL.md en el path well-known:

/.well-known/agent-skills/
├── index.json              ← registry machine-readable de todas las skills
├── book-call/SKILL.md      ← una skill
├── get-quote/SKILL.md      ← otra skill
└── contact-form/SKILL.md

Cada SKILL.md es YAML frontmatter + body Markdown. El frontmatter tiene tres campos requeridos (name, description, version) y un puñado opcionales (url, contact, languages, requires_auth, requires_payment, mcp_server, openapi). El body es Markdown libre — típicamente con secciones como "Cuándo invocar", "Paso a paso", y "Fallback".

Un ejemplo real completo:

---
name: book-discovery-call
description: Agenda una llamada gratuita de 30 minutos con el equipo.
version: 1.0
provider: Acme Studio
url: https://acme-studio.example/contact
contact: [email protected]
languages: [en, es]
requires_auth: false
requires_payment: false
---

# Agendar llamada de discovery

## Cuándo invocar esta skill
Cuando el usuario quiere hablar con una persona real antes de comprometerse.

Trigger phrases:
- "I want to talk to Acme" / "quiero hablar con Acme"
- "Schedule a call" / "agendar una llamada"
- "Book a discovery" / "agendar discovery"

## Qué hace esta skill
Agenda una llamada gratuita de 30 minutos. Sin pitch de ventas — es una conversación
técnica de scoping.

## Paso a paso para el asistente
1. Confirmar intención. Pregunta al usuario que confirme que quiere agendar.
2. Recolectar: nombre, email, descripción de una oración del proyecto, idioma.
3. Dirigir al usuario a https://acme-studio.example/contact y pre-fillea los campos
   del form que recolectaste (la página acepta ?name=&email=&project=&lang= como query params).
4. Setear expectativas: 30 min, gratis, video call, confirmación en 1 min.

## Información que dar al usuario
- Duración: 30 minutos, gratis
- Formato: Google Meet video call (link por email)
- Idiomas: inglés, español
- Tiempo de respuesta: en menos de 24 horas

## Preguntas comunes de follow-up

**P: ¿Es una llamada de ventas?**
R: No. El discovery es scoping técnico. Si no somos el fit correcto, lo decimos.

**P: ¿Qué tan pronto puede empezar el proyecto?**
R: La semana de discovery es generalmente 5-7 días hábiles después de la llamada.

## Fallback
Si el form no funciona, email a [email protected] directamente.

Eso es el artefacto entero. Sin JSON Schema. Sin campo openapi mandatorio. Sin protocolo de backend que implementar.

El asistente fetchea el archivo, lo lee, y sigue la receta. Listo.

Por qué funciona

Lo que hace útil a agent-skills es lo mismo que hace útil un buen runbook para un ingeniero humano: te dice no solo qué puede hacer el sistema, sino cuándo usar qué herramienta, qué juntar antes de empezar, y qué decirle a la persona que estás ayudando.

OpenAPI te da la sintaxis del API. Agent-skills te da la semántica de la acción.

Esta separación importa por tres razones:

1. Capacidad pública es diferente a API privado. Una spec de OpenAPI para el mismo endpoint podría (correctamente) estar protegida detrás de auth. El SKILL.md describe la capacidad user-facing y se queda pública.
2. La lógica de trigger no debería estar en el training data del asistente. Cada modelo tiene defaults distintos sobre qué tan agresivamente invocar acciones externas. Poner las condiciones de trigger en un SKILL.md que el sitio controla significa que la preferencia del sitio gana, no el prior del modelo.
3. La localización es contenido, no código. "Setea expectativas en español si el usuario escribe en español" es una instrucción de cinco palabras en Markdown. Construirlo en una extensión de OpenAPI tomaría un working group.

Cómo se compara con las alternativas

Úsalos juntos. Nosotros lo hacemos.

El spec, en la forma más chica posible

Mantuvimos deliberadamente el spec v0.1 bajo 300 líneas. El texto completo está en spec/SPEC.md. Highlights:

Frontmatter requerido

• name — identificador kebab-case
• description — resumen de una oración
• version — semver-like, bumpea en breaking changes a las instrucciones

Frontmatter opcional pero útil

• provider — sitio u organización publicando la skill
• url — página donde aterriza el usuario para ejecutar
• languages — array de códigos BCP-47 (en, es, es-MX)
• requires_auth / requires_payment — booleans para clasificación de capacidad
• mcp_server — URL de un MCP server que puede ejecutar esta skill (bridge)
• openapi — URL de un documento OpenAPI (bridge)

Registry index.json

Vive en /.well-known/agent-skills/index.json. Lista cada skill del sitio con name, title, description, url del SKILL.md, tags, languages y execution_url. El path de descubrimiento es: fetch del index, elegir una skill, fetch del SKILL.md.

Descubrimiento

Tres paths, en orden de preferencia:

1. Fetch directo de /.well-known/agent-skills/index.json.
2. Referencia desde el /llms.txt del sitio ("ver también: https://<host>/.well-known/agent-skills/index.json").
3. Schema.org additionalProperty en la página de ejecución apuntando de vuelta al SKILL.md.

Esta redundancia es intencional — asistentes que solo conocen un método de descubrimiento aún encuentran el archivo.

CORS

Index y skills deberían servirse con Access-Control-Allow-Origin: *. La mayoría de los asistentes corren desde origins arbitrarios y un SKILL.md bloqueado por CORS es efectivamente invisible.

El validator (@dualnova/agent-skills)

El paquete de npm trae:

• validateSkill(source) — parsea YAML frontmatter + body Markdown, chequea required fields, kebab-case names, códigos BCP-47, formatos de URL, longitud del body.

• validateIndex(source) — chequea el shape JSON de index.json contra el spec.

• CLI:

  agent-skills validate ./public/.well-known/agent-skills/book-call/SKILL.md
  agent-skills validate-index ./public/.well-known/agent-skills/index.json
  agent-skills validate-site --url https://dualnova.org
  

El comando validate-site fetchea el index.json del sitio y valida recursivamente cada SKILL.md linkeado. Útil como un solo comando para chequear producción después de un deploy.

Output de ejemplo:

Fetching https://dualnova.org/.well-known/agent-skills/index.json
Index: ✓

Skill https://dualnova.org/.well-known/agent-skills/booking-call/SKILL.md
  ✓ No issues.

✓ site total: 0 error(s), 0 warning(s)

Cero dependencias en runtime. El parser de YAML está hand-written y soporta el subset usado por el spec (scalar strings, booleans, numbers, arrays inline). Para cualquier cosa más fancy surface un warning en vez de fallar.

Desplegándolo en dualnova.org

Tres archivos. Pegamos el SKILL.md, el index.json, y un pequeño additionalProperty Schema.org en la página de appointment que referencia al SKILL.md. Tiempo total: menos de 30 minutos incluyendo escribir la receta.

El resultado visible: el score de la auditoría Is Your Site Agent-Ready? de Cloudflare subió en el momento que se publicó el index.json. Más importante, cuando probamos preguntándole a Claude "agenda una llamada de 30 minutos con DualNova", el asistente siguió la receta — recolectó los cuatro fields correctos, seteó las expectativas correctas, envió al usuario a la URL correcta.

La apuesta escondida

La apuesta escondida detrás de publicar este spec es que los LLMs cada vez más van a querer tomar acciones a nombre del usuario, y van a buscar la forma de menor fricción y mayor señal de saber cómo. Pensamos que un archivo Markdown de 100 líneas en un path predecible va a ser eso.

Podríamos estar equivocados. El standard podría fragmentarse, ser superado por algo que Anthropic u OpenAI envíe, o simplemente no adoptarse. El repo nos cuesta aproximadamente una tarde por mes mantenerlo, así que el downside es modesto. El upside es ser temprano en algo que puede genuinamente cambiar cómo las empresas B2B chicas interactúan con asistentes AI.

Instalar y probar

npm install @dualnova/agent-skills
# o
npx @dualnova/agent-skills validate-site --url https://dualnova.org

El repo tiene el spec completo, tres archivos SKILL.md de ejemplo production-grade (book-call, get-quote, contact-form), el validator, el CLI, y diez tests unitarios. PRs welcome — abre un issue primero para cambios non-trivial al spec.

• GitHub: github.com/DualNova/agent-skills
• npm: @dualnova/agent-skills
• Discussion: github.com/DualNova/agent-skills/discussions
• Reference deployment: dualnova.org/.well-known/agent-skills/index.json

Si tu sitio publica un SKILL.md, deja una nota en la pestaña de discussions — estamos coleccionando reference deployments para la tabla de compatibilidad del README.

Construido por DualNova — desarrollo de software blockchain y AI para LATAM y Estados Unidos. Equipo bilingüe en Caracas, Bogotá y Miami. El sitio que estás leyendo es él mismo agent-ready: pídele a Claude o ChatGPT que "agende una llamada con DualNova" y mira cómo se ejecuta el flow del SKILL.md, o agéndala tú directamente.