Agent Skills

À propos des Agent Skills

Docus découvre automatiquement les skills dans votre dossier skills/ et les sert à /.well-known/skills/, en suivant la RFC Agent Skills Discovery de Cloudflare. Vos skills sont ainsi installables depuis n'importe quelle URL de documentation avec une seule commande.

Les Agent Skills sont un format ouvert et léger pour donner aux agents IA des connaissances spécialisées et des workflows. Un skill est un fichier SKILL.md avec un frontmatter YAML qui décrit ce que les agents peuvent faire avec votre produit, accompagné de fichiers de référence optionnels.

Démarrage rapide

my-docs/
└── skills/
    └── my-product/
        └── SKILL.md

---
name: my-product
description: Build and deploy apps with My Product. Use when creating projects, configuring settings, or troubleshooting issues.
---

# My Product

## Getting Started

Create a new project:

\`\`\`bash
npx create-my-product my-app
\`\`\`

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

Structure du dossier

Un dossier de skill peut contenir des fichiers de support en plus du SKILL.md :

skills/
└── my-product/
    ├── SKILL.md              # Requis : instructions + métadonnées
    ├── references/           # Optionnel : documentation additionnelle
    │   ├── api.md
    │   └── configuration.md
    ├── scripts/              # Optionnel : code exécutable
    │   └── setup.sh
    └── assets/               # Optionnel : templates, schémas
        └── config.template.yaml

Tous les fichiers sont automatiquement listés dans le catalogue index.json et servis à leurs chemins respectifs sous /.well-known/skills/{skill-name}/.

Exigences pour les noms

Les noms de skills doivent suivre la spécification de nommage Agent Skills :

• 1-64 caractères
• Lettres minuscules, chiffres et tirets uniquement (a-z, 0-9, -)
• Ne doit pas commencer ou finir par un tiret
• Ne doit pas contenir de tirets consécutifs (--)
• Le champ name dans le frontmatter doit correspondre au nom du dossier parent

Skills multiples

Vous pouvez publier plusieurs skills depuis un seul site de documentation :

skills/
├── my-product/
│   └── SKILL.md
├── create-project/
│   ├── SKILL.md
│   └── references/
│       └── templates.md
└── migration-guide/
    └── SKILL.md

Tous les skills apparaissent dans le catalogue index.json et sont installables indépendamment.

Prévisualisation et versioning

Comme les skills vivent dans votre dépôt aux côtés de votre documentation, ils bénéficient de votre workflow Git existant :

• Previews de branches : Testez les modifications de skills sur des déploiements de preview avant de merger. Sur Vercel, chaque pull request obtient une URL de preview où vous pouvez vérifier que vos skills fonctionnent correctement :

npx skills add https://my-docs-git-feat-new-skill.vercel.app

• Contrôle de version : Suivez les changements de skills avec l'historique Git, reviewez les diffs dans les pull requests, et revenez en arrière si nécessaire.
• CI/CD : Les skills sont build et déployés automatiquement avec votre documentation — pas d'étape de publication séparée.

Fonctionnement de la découverte

Cette fonctionnalité implémente la RFC Agent Skills Discovery de Cloudflare, qui étend la RFC 8615 (le même standard .well-known derrière la validation de certificats ACME et security.txt).

Docus scanne votre dossier skills/ au moment du build et génère deux types d'endpoints :

Index de découverte

GET /.well-known/skills/index.json

Retourne un catalogue JSON listant tous les skills disponibles avec leurs descriptions et fichiers :

{
  "skills": [
    {
      "name": "my-product",
      "description": "Build and deploy apps with My Product.",
      "files": ["SKILL.md", "references/api.md"]
    }
  ]
}

Fichiers de skills

GET /.well-known/skills/{skill-name}/SKILL.md
GET /.well-known/skills/{skill-name}/references/api.md

Les fichiers individuels sont servis avec les types de contenu appropriés (text/markdown pour les .md, application/json pour les .json, etc.).

Comparaison avec llms.txt

llms.txt et les Agent Skills aident les outils d'IA à travailler avec votre documentation, mais ils servent des objectifs différents :