skill.md

Mintlify héberge un fichier skill.md à la racine de votre projet qui décrit ce que les agents d’IA peuvent faire avec votre produit.

La spécification skill.md est un format structuré et lisible par les machines qui rend explicites les capacités, les entrées requises et les contraintes des produits afin que les agents puissent les utiliser de manière plus fiable.

Mintlify génère automatiquement un fichier skill.md pour votre projet en analysant votre documentation avec une boucle pilotée par des agents. Ce fichier reste à jour à mesure que vous mettez à jour votre documentation et ne nécessite aucune maintenance. Vous pouvez également ajouter un fichier skill.md personnalisé à la racine de votre projet qui remplace celui généré automatiquement.

Affichez votre skill.md en ajoutant /skill.md à l’URL de votre site de documentation. Mintlify ne génère des fichiers skill.md que pour les sites de documentation publics.

Lorsque les utilisateurs se connectent à votre serveur MCP, leurs agents peuvent découvrir et utiliser vos fichiers skill.md en tant que ressources MCP sans installer les skills séparément.

Pour ajouter vos skills au contexte d’un agent manuellement, utilisez la CLI skills.

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

Cela ajoute les capacités de votre produit au contexte de l’agent afin qu’il puisse effectuer des actions au nom des utilisateurs.

Mintlify génère un fichier skill.md selon la spécification agentskills.io. Le fichier généré comprend :

• Metadata : nom du projet, description et version.
• Capacités : ce que les agents peuvent accomplir avec votre produit.
• Compétences : actions spécifiques organisées par catégorie.
• Flux de travail : procédures étape par étape pour les tâches courantes.
• Intégrations : outils et services pris en charge.
• Contexte : informations générales sur l’architecture de votre produit.

Ajoutez des fichiers de skill personnalisés pour remplacer le skill.md généré automatiquement. Mintlify prend en charge l’hébergement d’un fichier de skill unique et d’un répertoire pour plusieurs skills. Si vous supprimez tous les fichiers de skill personnalisés, Mintlify génère un nouveau fichier skill.md.

Ajoutez un fichier skill.md à la racine de votre projet pour remplacer le fichier généré automatiquement.

Ajoutez plusieurs fichiers de skill au répertoire .mintlify/skills/ de votre projet. Chaque skill doit se trouver dans son propre sous-répertoire avec un fichier SKILL.md :

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

Lorsque vous disposez de plusieurs skills, l’endpoint /skill.md redirige vers l’endpoint de découverte /.well-known/skills/index.json, qui liste toutes les skills disponibles. Les endpoints de découverte rendent chaque skill accessible individuellement.

Si vos fichiers de skill se trouvent ailleurs dans votre dépôt (par exemple, dans un répertoire plugins/ ou skills/), vous pouvez créer un lien symbolique de .mintlify/skills vers cet emplacement au lieu de dupliquer les fichiers :

# 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 résout les liens symboliques lors du déploiement, ce qui lui permet de découvrir et de servir les fichiers de skill comme s’ils se trouvaient directement dans .mintlify/skills/. Cela fonctionne aussi bien avec les liens symboliques de répertoires qu’avec les liens symboliques de skills individuels.

Les fichiers skill.md personnalisés doivent commencer par un frontmatter YAML.

---
name: mintlify
description: Créez et maintenez des sites de documentation avec Mintlify. À utiliser lors de la création de pages de documentation, de la configuration de la navigation, de l'ajout de composants ou de la mise en place de références API.
license: MIT
compatibility: Nécessite Node.js pour l'interface en ligne de commande (CLI). Fonctionne avec tout workflow basé sur Git.
metadata:
  author: mintlify
  version: "1.0"
---

Si votre documentation utilise l’authentification, vous pouvez restreindre un skill à des groupes d’utilisateurs spécifiques en ajoutant un tableau groups à son frontmatter. Le filtrage par groupes fonctionne comme la visibilité des pages : le skill n’est exposé qu’aux utilisateurs authentifiés qui appartiennent à au moins un des groupes listés.

---
name: admin-tools
description: Opérations internes pour les administrateurs.
groups: ["admin"]
---

Les skills restreints par groupes :

• Sont masqués des endpoints publics de découverte et du fichier public /skill.md.
• Sont exposés en tant que ressources MCP uniquement aux utilisateurs finaux authentifiés dont les groupes correspondent. Les utilisateurs qui ne correspondent pas et les clients machine à machine sans utilisateur final ne voient que les skills sans groupes.

Les skills sans champ groups restent visibles pour tous.

Mintlify héberge des répertoires de skills à /.well-known/skills/ et /.well-known/agent-skills/ que les agents peuvent utiliser pour découvrir et récupérer vos fichiers de skills de manière programmatique.

L’endpoint /.well-known/agent-skills/ suit la spécification agent-skills discovery 0.2.0 et inclut la vérification d’intégrité du contenu.

GET /.well-known/agent-skills/index.json renvoie un manifeste JSON listant toutes les 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..."
    }
  ]
}

GET /.well-known/agent-skills/{name}/SKILL.md renvoie le fichier skill.md d’une skill spécifique identifiée par son nom slugifié depuis l’index.

L’endpoint /.well-known/skills/ est le format de découverte original.

GET /.well-known/skills/index.json renvoie un manifeste JSON listant toutes les skills disponibles :

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

Le champ name est un slug compatible URL dérivé du champ name dans le frontmatter de votre skill.md.

GET /.well-known/skills/{name}/skill.md renvoie le fichier skill.md d’une skill spécifique identifiée par son nom slugifié depuis l’index.

Mintlify héberge une carte d’agent Agent-to-Agent (A2A) à l’adresse /.well-known/agent-card.json. La carte d’agent est un document JSON standardisé qui permet aux agents compatibles A2A de découvrir votre site de documentation et les skills disponibles en une seule requête.

GET /.well-known/agent-card.json renvoie un document JSON conforme au schéma 0.3 de la carte d’agent A2A. Chaque entrée du tableau skills correspond à une skill provenant de vos endpoints de découverte de skills.

Les agents compatibles A2A récupèrent /.well-known/agent-card.json pour découvrir votre site par son nom et sa description, suivent documentationUrl pour obtenir du contenu lisible par un humain, et parcourent skills pour récupérer chaque fichier skill.md. La carte expose également un tableau supportedInterfaces afin que les agents puissent négocier le transport avant d’envoyer une requête.

Les URL de la carte (url, documentationUrl, provider.url et chaque URL de skill) sont construites à partir du domaine personnalisé configuré lorsqu’il est défini, afin que la carte publiée annonce toujours le domaine canonique au lieu du sous-domaine *.mintlify.site.

La carte d’agent complète MCP en fournissant une couche de découverte légère qui ne nécessite pas l’établissement d’une session.