Docsbook
Aperçu

docs-skills : capacités modulaires pour les agents IA sur les docs

En 2026, les agents IA ne se contentent pas de lire la documentation — ils agissent sur celle-ci. Ils publient un site de docs, corrigent des liens brisés, génèrent llms.txt, écrivent des pages manquantes, audite l'accessibilité. La façon dont ils savent comment effectuer ces actions est à travers des "compétences" — descriptions de capacités empaquetées, découvrables et déclaratives.

Ce post explique ce que sont les compétences, ce que contient aujourd'hui le catalogue open-source de Docsbook, et comment la couche s'intègre entre MCP et votre contenu.

TL;DR#

  • Une "compétence" est un SKILL.md fichier avec des métadonnées qui décrit une capacité — ce qu'elle fait, quand la déclencher, quels outils elle nécessite
  • Les agents IA (Claude Code, Cursor) lisent les compétences et les exécutent de manière autonome
  • docs-skills est un catalogue open-source de quatre compétences documentaires
  • Docsbook MCP expose find_skill afin que les agents découvrent les compétences par requête à l'exécution
  • Vous pouvez installer des compétences localement (npx docs-skills install) ou les utiliser via MCP

À quoi ressemble une compétence#

Un minimal SKILL.md:

---
name: docs-pr-check
description: Validate documentation changes in a pull request — check for broken links, missing frontmatter, accessibility issues, and SEO regressions. Use when reviewing docs PRs.
category: automation
mode: agent
keywords: [pull request, broken links, frontmatter, review]
requires_docsbook_mcp: true
version: 1
---
 
# docs-pr-check
 
When the user opens a docs PR, run this skill to validate the change.
 
Steps:
 
1. Run `doc_search_unresolved` to find broken links in changed files
2. Verify YAML frontmatter on every new or modified `.md` file
3. Check that internal links resolve
4. Suggest improvements
 
Tools used: `doc_search_unresolved`, `doc_outline`, `doc_resolve_link` (Docsbook MCP)

La compétence ci-dessus est une illustration du format, pas une entrée dans le catalogue — les quatre vraies compétences sont listées plus bas. Les champs de frontmatter sont ceux que le schéma définit réellement : name, description, category, mode, keywords, requires_docsbook_mcp et version.

Le frontmatter est le contrat. Le corps est l'invite.

Pourquoi cela importe pour la documentation#

Trois problèmes que les compétences résolvent :

1. Découverte des capacités#

Sans compétences, un agent IA lisant vos documents MCP doit deviner quoi faire. Avec des compétences, l'agent appelle find_skill("audit my docs") et obtient un SKILL.md avec des instructions exactes.

2. Réutilisation modulaire#

Une compétence écrite pour un projet fonctionne sur n'importe quel projet. docs-manage est le livre de règles pour écrire une page et faire fonctionner le site sur lequel elle se trouve, et il s'applique à tout dépôt de documentation, sur Docsbook ou non.

3. Composition#

Les compétences se composent plutôt que de se multiplier. Chacune porte un references/ répertoire de documents ciblés qu'elle charge uniquement lorsque la tâche en a besoin — docs-manage seul détient des références séparées pour la récupération, la conversion et les règles d'écriture. L'agent lit la compétence, puis lit la seule référence qui compte, au lieu de charger un catalogue.

Le catalogue des compétences#

Qu'est-ce qui se trouve dans le catalogue des compétences de la documentation ?#

docs-skills est un catalogue open-source de quatre compétences, chacune couvrant un travail qu'un agent effectue avec la documentation. Auparavant, c'était une longue liste de compétences étroites ; elle a été consolidée car un agent choisissant entre cinquante descriptions presque synonymes fait de mauvais choix, et quatre emplois sont distincts.

Compétence Le travail qu'elle effectue
docs-create Créer une documentation qui n'existait pas — à partir d'un site web produit, d'un dépôt de code, d'une autre plateforme de documentation dont vous migrez, ou rien d'autre qu'un nom de produit
docs-analyze Identifier ce qui ne va pas avec la documentation qui existe déjà et le corriger, en partant des positions de recherche, des signaux de réponse AI, du comportement des lecteurs et des entonnoirs
docs-manage Le manuel pour rédiger une page et pour gérer le site sur lequel elle se trouve — type de page, structure, style, public, récupération, conversion
docs-automate Mettre en place les choses qui devraient continuer à se produire sans que personne ne s'en souvienne — gardes de dérive, déclencheurs de traduction, annonces de publication

Chaque compétence est un SKILL.md autonome dans le dépôt GitHub, avec un répertoire references/ que l'agent lit à la demande. L'index lisible par machine est index.json dans le même dépôt ; les comptes ci-dessus ont été lus à partir de celui-ci le 2026-09-03.

Deux façons d'utiliser les compétences#

Installation locale#

npx docs-skills install

Copie le catalogue dans .claude/skills/, .cursor/rules/, ou AGENTS.md (selon l'outil détecté). Fonctionne hors ligne. Se met à jour avec docs-skills update.

Ce modèle : les compétences de vos outils vivent dans votre dépôt, sous contrôle de version.

Découverte à l'exécution via MCP#

Si vous avez Docsbook MCP connecté, votre agent appelle :

find_skill({ query: "audit my docs for SEO and accessibility" })

Il renvoie les compétences les mieux correspondantes avec raw_url pour chaque SKILL.md. L'agent récupère et suit les instructions.

Ce modèle : pas d'installation locale, toujours la dernière version, fonctionne sur plusieurs machines.

Comment les agents IA utilisent les compétences en pratique#

Trois flux de travail réels que nous avons observés :

Workflow 1 : Revue de PR#

Un développeur ouvre une PR qui touche docs/. Leur Claude Code (ou Cursor) invoque docs-pr-check. La compétence :

  1. Liste les fichiers .md modifiés
  2. Appelle doc_search_unresolved sur chacun
  3. Vérifie l'exhaustivité des frontmatter
  4. Rapporte les résultats en tant que commentaire de PR

Le développeur voit le rapport avant qu'un examinateur humain ne le fasse. De nombreux problèmes de documentation n'atteignent jamais l'équipe.

Flux de travail 2 : Détection de contenu obsolète#

Le cron hebdomadaire dans la configuration de l'utilisateur invoque docs-stale-watcher. La compétence :

  1. Interroge les analyses Docsbook pour les pages avec du trafic mais sans modifications depuis plus de 90 jours
  2. Fait des références croisées avec le graphique des documents
  3. Liste les candidats pour une mise à jour

La sortie est un backlog de pages à mettre à jour — des lacunes de contenu avec un signal de revenus.

Flux de travail 3 : réglage du chat IA#

L'utilisateur dit "mon chat IA hallucine à propos de la fonctionnalité X." L'agent invoque docs-tune-ai-chat. La compétence :

  1. Appelle get_ai_questions pour voir les requêtes récentes sans réponse
  2. Appelle get_negative_feedback pour voir les modèles de pouces vers le bas
  3. Identifie le contenu manquant ou faible
  4. Suggère une nouvelle page ou un changement de prompt système

C'est la boucle "l'agent améliore l'agent".

Compétences + MCP : l'architecture#

Les compétences indiquent à l'agent quoi faire. Les outils MCP indiquent à l'agent comment le faire.

  • Une compétence dit "auditer l'accessibilité de chaque page"
  • Le corps de la compétence énumère des étapes comme "appeler doc_list_pages, puis doc_outline sur chacune"
  • MCP expose les outils réels que la compétence invoque

Aucun des deux n'est suffisant seul. Ensemble, ils forment une boucle complète : découverte (find_skill) → instructions (SKILL.md) → exécution (outils MCP).

À quoi cela ressemble pour vos propres documents#

Si vous expédiez un produit destiné aux développeurs et que vous souhaitez que les agents IA interagissent bien avec vos documents, trois étapes :

  1. Publiez sur une plateforme avec llms.txt — Docsbook en génère un automatiquement par espace de travail
  2. Exposez un serveur MCP ou comptez sur celui de la plateforme — Docsbook MCP est inclus
  3. Installez les compétences documentaires pertinentes localement — npx docs-skills install

Après cela, tout agent (Claude Code, Cursor, ChatGPT avec HTTP MCP) peut travailler de manière autonome avec vos documents.

Créez votre propre compétence#

Si vous avez un flux de travail de documentation qui n'est pas dans le catalogue, contribuez-en un. Le format SKILL.md est simple, le catalogue est public, les contributions sont publiées en quelques jours.

Une compétence utile est :

  • Spécifique (un travail, bien fait)
  • Composable (appelle des outils MCP existants)
  • Déclenchée par une intention utilisateur claire
  • Documentée avec des exemples

Le dépôt a un SKILL.md modèle et un guide de contribution.

Docsbook propose un support pour les compétences-docs : l'outil MCP find_skill pour la découverte en temps réel, et npx docs-skills install pour une copie locale. Publiez un espace de travail et le point de terminaison MCP vient avec — les étapes de configuration se trouvent sur docsbook.io/mcp.

Commencez gratuitement — pas de carte de crédit

Étapes suivantes#

Updated

Cette page vous a-t-elle été utile ?

Propulsé par Docsbook