skill.md

Mintlify aloja un archivo skill.md en la raíz de tu proyecto que describe lo que los agentes de IA pueden hacer con tu producto. La especificación de skill.md es un formato estructurado y legible por máquinas que hace explícitas las capacidades, los datos de entrada obligatorios y las restricciones de los productos para que los agentes puedan utilizarlos de forma más confiable. Mintlify genera automáticamente un archivo skill.md para tu proyecto analizando tu documentación con un bucle de agentes. Este archivo se mantiene actualizado a medida que realizas cambios en tu documentación y no requiere mantenimiento. Opcionalmente, puedes añadir un archivo skill.md personalizado en la raíz de tu proyecto que reemplace al generado automáticamente.

Generar o actualizar un archivo skill.md puede tardar hasta 24 horas.

Consulta tu skill.md añadiendo /skill.md a la URL de tu sitio de documentación. Mintlify solo genera archivos skill.md para sitios de documentación que sean públicos.

Tanto los archivos llms.txt como skill.md ayudan a los agentes a trabajar con tu documentación, pero cumplen funciones diferentes.

llms.txt es un directorio. Enumera todas las páginas de tu documentación con descripciones para que los agentes sepan dónde encontrar la información.
skill.md es un resumen de capacidades. Indica a los agentes qué pueden lograr con tu producto, qué datos de entrada necesitan y qué restricciones se aplican.

Usa archivos `skill.md` con agentes

Si utilizas un proxy inverso, configúralo para reenviar las rutas /skill.md, /.well-known/skills/* y /.well-known/agent-skills/* a tu subdominio de Mintlify. Consulta la configuración de enrutamiento para conocer las rutas de destino y las políticas de caché.

Cuando los usuarios se conectan a tu servidor MCP, sus agentes pueden descubrir y usar tus archivos skill.md como recursos MCP sin necesidad de instalar los skills por separado. Para agregar tus skills al contexto de un agente manualmente, usa la CLI de skills.

npx skills add https://your-docs-domain.com

Esto añade las capacidades de tu producto al contexto del agente para que pueda realizar acciones en nombre de los usuarios.

Enseña a tus usuarios cómo usar archivos skill.md con agentes para que obtengan mejores resultados al utilizar tu producto con sus herramientas de IA.

Estructura de `skill.md`

Mintlify genera un archivo skill.md siguiendo la especificación de agentskills.io. El archivo generado incluye:

Metadatos: Nombre del proyecto, descripción y versión.
Capacidades: Lo que los agentes pueden hacer con tu producto.
Habilidades: Acciones específicas organizadas por categoría.
Flujos de trabajo: Procedimientos paso a paso para tareas comunes.
Integración: Herramientas y servicios compatibles.
Contexto: Información contextual sobre la arquitectura de tu producto.

Archivos de skill personalizados

Añade archivos de skill personalizados para reemplazar el skill.md generado automáticamente. Mintlify admite alojar un único archivo de skill y un directorio para múltiples skills. Si eliminas todos los archivos de skill personalizados, Mintlify genera un nuevo archivo skill.md.

Archivo de skill único

Añade un archivo skill.md a la raíz de tu proyecto para reemplazar el archivo generado automáticamente.

Múltiples archivos de skill

Añade múltiples archivos de skill al directorio .mintlify/skills/ de tu proyecto. Cada skill debe estar en su propio subdirectorio con un archivo SKILL.md:

.mintlify/
  skills/
    payments/
      SKILL.md
    analytics/
      SKILL.md

Cuando tienes múltiples skills, el endpoint /skill.md redirige al endpoint de descubrimiento /.well-known/skills/index.json, que lista todas las skills disponibles. Los endpoints de descubrimiento hacen que cada skill sea accesible individualmente.

Puedes usar ambos enfoques juntos con un archivo skill.md en la raíz y un directorio .mintlify/skills/. El índice de descubrimiento incluye todas las skills.

Usa enlaces simbólicos para evitar duplicación

Si tus archivos de skill están en otra ubicación de tu repositorio (por ejemplo, en un directorio plugins/ o skills/), puedes crear un enlace simbólico de .mintlify/skills hacia esa ubicación en lugar de duplicar archivos:

# Skills live in a top-level skills/ directory
ln -s ../skills .mintlify/skills

project/
  skills/
    payments/
      SKILL.md
    analytics/
      SKILL.md
  .mintlify/
    skills -> ../skills
  docs.json

Mintlify resuelve los enlaces simbólicos durante el despliegue, por lo que descubre y sirve los archivos de skill como si estuvieran directamente dentro de .mintlify/skills/. Esto funciona tanto con enlaces simbólicos de directorios como de skills individuales.

Campos de frontmatter

Los archivos skill.md personalizados deben comenzar con frontmatter YAML.

Campo	Tipo	Descripción
`name`	string	El nombre de tu skill.
`description`	string	Una breve descripción de lo que hace tu skill.
`license`	string	La licencia de tu skill (por ejemplo, `MIT` o `Apache-2.0`).
`compatibility`	string	Requisitos o notas de compatibilidad (por ejemplo, dependencias de tiempo de ejecución).
`metadata`	object	metadata adicional representada como pares key-value de tipo string (por ejemplo, `author` o `version`).
`allowed-tools`	string	Lista delimitada por espacios de herramientas preaprobadas que la skill puede usar (experimental).
`groups`	array	Restringe la skill a grupos específicos de usuarios autenticados. Consulta Restringir skills a grupos de usuarios.

Example frontmatter

---
name: mintlify
description: Construye y mantén sitios de documentación con Mintlify. Úsalo al crear páginas de documentación, configurar la navegación, agregar componentes o configurar referencias de API.
license: MIT
compatibility: Requiere Node.js para CLI. Funciona con cualquier flujo de trabajo basado en Git.
metadata:
  author: mintlify
  version: "1.0"
---

Restringir skills a grupos de usuarios

Si tu documentación usa autenticación, puedes restringir una skill a grupos específicos de usuarios añadiendo un arreglo groups a su frontmatter. El filtrado por grupos funciona igual que la visibilidad de páginas: la skill solo se expone a los usuarios autenticados que pertenecen al menos a uno de los grupos indicados.

SKILL.md

---
name: admin-tools
description: Operaciones internas para administradores.
groups: ["admin"]
---

Las skills restringidas por grupos:

Se ocultan de los endpoints públicos de descubrimiento y del archivo público /skill.md.
Se exponen como recursos MCP solo a los usuarios autenticados cuyos grupos coinciden. Los usuarios que no coinciden y los clientes máquina a máquina sin usuario final solo ven las skills sin grupos.

Las skills sin el campo groups permanecen visibles para todos.

Validar un archivo de skill personalizado

Antes de desplegar, verifica que tus archivos de skill personalizados sean válidos:

Comprueba el frontmatter. Cada archivo de skill personalizado debe comenzar con frontmatter YAML que incluya al menos un name y una description. Consulta Campos de frontmatter para ver la lista completa de campos admitidos.
Previsualiza en local. Ejecuta mint dev para servir tu sitio localmente y abre http://localhost:3000/skill.md para comprobar que se carga tu archivo personalizado en lugar del generado.
Verifica después de desplegar. Cuando se despliegue tu sitio, añade /skill.md a la URL de tu sitio para ver el archivo de skill servido. Si tienes varias skills, obtén /.well-known/agent-skills/index.json para confirmar que cada skill personalizada aparece en el manifiesto de descubrimiento.
Valida contra la especificación. Compara tu archivo con la especificación de agentskills.io para confirmar que las secciones obligatorias están presentes y con el formato correcto.

Los cambios en los archivos de skill personalizados se publican con tu siguiente despliegue. Como las skills generadas pueden tardar hasta 24 horas en actualizarse, las skills personalizadas son la forma más rápida de controlar lo que ven los agentes.

Endpoints de descubrimiento de skills

Mintlify aloja directorios de skills en /.well-known/skills/ y /.well-known/agent-skills/ que los agentes pueden usar para descubrir y obtener tus archivos de skills de forma programática.

Descubrimiento agent-skills (recomendado)

El endpoint /.well-known/agent-skills/ sigue la especificación agent-skills discovery 0.2.0 e incluye verificación de integridad del contenido. GET /.well-known/agent-skills/index.json devuelve un manifiesto JSON con la lista de todas las skills disponibles:

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "my-product",
      "type": "skill-md",
      "description": "A brief description of what your skill does.",
      "url": "/.well-known/agent-skills/my-product/SKILL.md",
      "digest": "sha256:a1b2c3..."
    }
  ]
}

Campo	Descripción
`$schema`	URL del esquema para la especificación agent-skills discovery 0.2.0.
`name`	Un slug seguro para URL derivado del campo `name` en el frontmatter de tu `skill.md`.
`type`	El formato de la skill. Siempre `skill-md`.
`description`	Una breve descripción del frontmatter de tu `skill.md`, truncada a 1024 caracteres.
`url`	La ruta para obtener el archivo de skill completo.
`digest`	Un hash `sha256` del contenido del archivo de skill para verificación de integridad.

GET /.well-known/agent-skills/{name}/SKILL.md devuelve el archivo skill.md de una skill específica identificada por su nombre slugificado del índice.

Índice de skills

El endpoint /.well-known/skills/ es el formato de descubrimiento original. GET /.well-known/skills/index.json devuelve un manifiesto JSON con la lista de todas las skills disponibles:

{
  "skills": [
    {
      "name": "my-product",
      "description": "A brief description of what your skill does.",
      "files": ["SKILL.md"]
    }
  ]
}

El campo name es un slug seguro para URL derivado del campo name en el frontmatter de tu skill.md.

Archivos de skills individuales

GET /.well-known/skills/{name}/skill.md devuelve el archivo skill.md de una skill específica identificada por su nombre slugificado del índice.

Tarjeta de agente

Mintlify aloja una tarjeta de agente Agent-to-Agent (A2A) en /.well-known/agent-card.json. La tarjeta de agente es un documento JSON estandarizado que ayuda a los agentes compatibles con A2A a descubrir tu sitio de documentación y las skills disponibles en una sola solicitud. GET /.well-known/agent-card.json devuelve un documento JSON conforme al esquema 0.3 de tarjeta de agente A2A. Cada entrada del arreglo skills corresponde a una skill de tus endpoints de descubrimiento de skills. Los agentes compatibles con A2A obtienen /.well-known/agent-card.json para descubrir tu sitio por su nombre y descripción, siguen documentationUrl para recuperar contenido legible por humanos, e iteran sobre skills para obtener cada archivo skill.md. La tarjeta también expone un arreglo supportedInterfaces para que los agentes puedan negociar el transporte antes de hacer una solicitud.

Campo	Descripción
`protocolVersion`	Versión del protocolo A2A. Siempre `0.3`.
`preferredTransport`	Transporte por defecto para clientes que no negocian. Siempre `HTTP+JSON`.
`supportedInterfaces`	Arreglo de entradas `{ url, protocolBinding, protocolVersion }` que describen cómo los agentes acceden al sitio.
`provider`	`{ url, organization }` que identifica el sitio de documentación. `organization` es el título del sitio.
`defaultInputModes`	Tipos de medios que acepta el agente como entrada. Siempre `["text/plain"]`.
`defaultOutputModes`	Tipos de medios que produce el agente. Siempre `["text/plain"]`.
`capabilities`	Indicadores de funcionalidades. Actualmente `{ streaming: false, pushNotifications: false }`.
`skills`	Las skills expuestas en `/.well-known/agent-skills/`.

Las URL de la tarjeta (url, documentationUrl, provider.url y cada URL de skill) se construyen a partir del dominio personalizado configurado cuando está disponible, de modo que la tarjeta publicada siempre anuncia el dominio canónico en lugar del subdominio *.mintlify.site.

Si usas un reverse proxy, configúralo para reenviar /.well-known/agent-card.json a tu subdominio de Mintlify.

La tarjeta de agente complementa MCP al proporcionar una capa de descubrimiento ligera que no requiere establecer una sesión.

Primeros pasos

Organizar

Personalizar

Crear contenido

Documentar APIs

Desplegar

Optimizar

Usa archivos `skill.md` con agentes

Estructura de `skill.md`

Archivos de skill personalizados

Archivo de skill único

Múltiples archivos de skill

Usa enlaces simbólicos para evitar duplicación

Campos de frontmatter

Restringir skills a grupos de usuarios

Validar un archivo de skill personalizado

Endpoints de descubrimiento de skills

Descubrimiento agent-skills (recomendado)

Índice de skills

Archivos de skills individuales

Tarjeta de agente

​Usa archivos skill.md con agentes

​Estructura de skill.md

​Archivos de skill personalizados

​Archivo de skill único

​Múltiples archivos de skill

​Usa enlaces simbólicos para evitar duplicación

​Campos de frontmatter

​Restringir skills a grupos de usuarios

​Validar un archivo de skill personalizado

​Endpoints de descubrimiento de skills

​Descubrimiento agent-skills (recomendado)

​Índice de skills

​Archivos de skills individuales

​Tarjeta de agente

Usa archivos `skill.md` con agentes

Estructura de `skill.md`

Archivos de skill personalizados

Archivo de skill único

Múltiples archivos de skill

Usa enlaces simbólicos para evitar duplicación

Campos de frontmatter

Restringir skills a grupos de usuarios

Validar un archivo de skill personalizado

Endpoints de descubrimiento de skills

Descubrimiento agent-skills (recomendado)

Índice de skills

Archivos de skills individuales

Tarjeta de agente