mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
9ee2f23b37
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
280 lines
15 KiB
Plaintext
280 lines
15 KiB
Plaintext
---
|
|
title: "skill.md"
|
|
description: "Haz que tu documentación esté lista para agentes con archivos skill.md generados automáticamente que describen las capacidades de tu producto a la IA."
|
|
keywords: ["agentes de IA", "habilidades", "habilidades de agente", "agentes"]
|
|
boost: 3
|
|
---
|
|
|
|
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](https://agentskills.io/specification) 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.
|
|
|
|
<Note>Generar o actualizar un archivo `skill.md` puede tardar hasta 24 horas.</Note>
|
|
|
|
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.
|
|
|
|
<PreviewButton href="https://mintlify.com/docs/skill.md">
|
|
Abrir el skill.md de este sitio.
|
|
</PreviewButton>
|
|
|
|
<Tip>
|
|
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.
|
|
</Tip>
|
|
|
|
<div id="use-skillmd-files-with-agents">
|
|
## Usa archivos `skill.md` con agentes
|
|
</div>
|
|
|
|
<Note>
|
|
Si utilizas un [proxy inverso](/es/deploy/reverse-proxy), 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](/es/deploy/reverse-proxy#routing-configuration) para conocer las rutas de destino y las políticas de caché.
|
|
</Note>
|
|
|
|
Cuando los usuarios se conectan a tu servidor MCP, sus agentes pueden descubrir y usar tus archivos `skill.md` como [recursos MCP](/es/ai/model-context-protocol#mcp-resources) sin necesidad de instalar los skills por separado.
|
|
|
|
Para agregar tus skills al contexto de un agente manualmente, usa la [CLI de skills](https://www.npmjs.com/package/skills).
|
|
|
|
```bash
|
|
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.
|
|
|
|
{/* vale off */}
|
|
|
|
<Prompt description="Instala los archivos skill.md de un producto en tu agente." actions={["copy", "cursor"]}>
|
|
Instala los archivos `skill.md` de un sitio de documentación alojado en Mintlify en el contexto de mi agente para que sepas qué puede hacer este producto.
|
|
|
|
1. Pídeme la URL del sitio de documentación si aún no la he proporcionado, luego ejecuta `npx skills add <url>` con esa URL.
|
|
2. Muestra la lista de skills que se instalaron, incluyendo el nombre y la descripción de cada skill.
|
|
3. Resume las capacidades clave en un párrafo para que sepa con qué puedes ayudarme ahora usando este producto.
|
|
4. Si alguna skill declara entradas obligatorias o restricciones en su frontmatter, indícamelo antes de que te pida que la uses.
|
|
</Prompt>
|
|
|
|
{/* vale on */}
|
|
|
|
<Tip>
|
|
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.
|
|
</Tip>
|
|
|
|
<div id="skillmd-structure">
|
|
## Estructura de `skill.md`
|
|
</div>
|
|
|
|
Mintlify genera un archivo `skill.md` siguiendo la [especificación de agentskills.io](https://agentskills.io/specification). 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.
|
|
|
|
<div id="custom-skill-files">
|
|
## Archivos de skill personalizados
|
|
</div>
|
|
|
|
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`.
|
|
|
|
<div id="single-skill-file">
|
|
### Archivo de skill único
|
|
</div>
|
|
|
|
Añade un archivo `skill.md` a la raíz de tu proyecto para reemplazar el archivo generado automáticamente.
|
|
|
|
<div id="multiple-skill-files">
|
|
### Múltiples archivos de skill
|
|
</div>
|
|
|
|
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.
|
|
|
|
<Note>
|
|
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.
|
|
</Note>
|
|
|
|
<div id="use-symlinks-to-avoid-duplication">
|
|
### Usa enlaces simbólicos para evitar duplicación
|
|
</div>
|
|
|
|
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:
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
<div id="frontmatter-fields">
|
|
### Campos de frontmatter
|
|
</div>
|
|
|
|
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](#restrict-skills-to-user-groups). |
|
|
|
|
```md 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"
|
|
---
|
|
```
|
|
|
|
<div id="restrict-skills-to-user-groups">
|
|
### Restringir skills a grupos de usuarios
|
|
</div>
|
|
|
|
Si tu documentación usa [autenticación](/es/deploy/authentication-setup), 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](/es/create/personalization#page-visibility): la skill solo se expone a los usuarios autenticados que pertenecen al menos a uno de los grupos indicados.
|
|
|
|
```md 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](#skills-discovery-endpoints) y del archivo público `/skill.md`.
|
|
- Se exponen como [recursos MCP](/es/ai/model-context-protocol#mcp-resources) 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.
|
|
|
|
<div id="skills-discovery-endpoints">
|
|
## Endpoints de descubrimiento de skills
|
|
</div>
|
|
|
|
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.
|
|
|
|
<div id="agent-skills-discovery">
|
|
### Descubrimiento agent-skills (recomendado)
|
|
</div>
|
|
|
|
El endpoint `/.well-known/agent-skills/` sigue la [especificación agent-skills discovery 0.2.0](https://schemas.agentskills.io/discovery/0.2.0/schema.json) 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:
|
|
|
|
```json
|
|
{
|
|
"$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.
|
|
|
|
<div id="skills-index">
|
|
### Índice de skills
|
|
</div>
|
|
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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`.
|
|
|
|
<div id="individual-skill-files">
|
|
### Archivos de skills individuales
|
|
</div>
|
|
|
|
`GET /.well-known/skills/{name}/skill.md` devuelve el archivo `skill.md` de una skill específica identificada por su nombre slugificado del índice.
|
|
|
|
<div id="agent-card">
|
|
## Tarjeta de agente
|
|
</div>
|
|
|
|
Mintlify aloja una tarjeta de agente [Agent-to-Agent (A2A)](https://a2aproject.github.io/A2A/latest/) 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](https://a2aproject.github.io/A2A/latest/specification/#agent-card). 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`.
|
|
|
|
<Note>
|
|
Si usas un [reverse proxy](/es/deploy/reverse-proxy), configúralo para reenviar `/.well-known/agent-card.json` a tu subdominio de Mintlify.
|
|
</Note>
|
|
|
|
La tarjeta de agente complementa [MCP](/es/ai/model-context-protocol) al proporcionar una capa de descubrimiento ligera que no requiere establecer una sesión.
|