Compétences de l’agent

Utilisez le fichier SKILL.md officiel de GitBook pour donner aux assistants de codage IA comme Claude Code, Cursor ou Codex la connaissance des fonctionnalités et blocs de GitBook

GitBook fournit des fichiers de compétences qui apprennent aux assistants de code IA à modifier correctement la documentation GitBook. Si vous utilisez Claude Code, Cursor, Codex ou un autre assistant de code externe, ajoutez les compétences GitBook afin que votre agent puisse travailler avec la syntaxe, les blocs et les fichiers de configuration de GitBook.

Cela s'intègre parfaitement aux flux de travail Git Sync — apportez des modifications dans votre dépôt, validez-les, et votre site de documentation se met à jour automatiquement.

Vous préférez écrire dans l'éditeur GitBook ? Utilisez GitBook Agent pour rédiger, réécrire, relire et traduire du contenu sans quitter GitBook.

Ajoutez des compétences GitBook à votre agent IA

Utilisez cette option lorsque votre assistant de code IA prend en charge les compétences basées sur des paquets.

1

Créer un jeton d'accès

Pour permettre à votre agent d'interagir avec GitBook, vous devez créer un jeton d'accès depuis les paramètres développeur de GitBook. GitBook utilise ce jeton pour authentifier votre agent lorsqu'il travaille avec les compétences GitBook.

2

Installer les compétences GitBook

Cette compétence fait partie du gitbook-skills dépôt. Exécutez la commande suivante pour installer les compétences GitBook directement dans votre projet :

npx skills add GitBookIO/gitbook-skills

Ajouter les compétences GitBook localement

Téléchargez les compétences GitBook si votre assistant ne prend pas en charge les compétences basées sur des paquets.

1

Créer un jeton d'accès

Pour permettre à votre agent d'interagir avec GitBook, vous devez créer un jeton d'accès depuis les paramètres développeur de GitBook. GitBook utilise ce jeton pour authentifier votre agent lorsqu'il travaille avec les compétences GitBook.

2

Télécharger les compétences GitBook

Installez les compétences GitBook avec npx skills add GitBookIO/gitbook-skills lorsque votre assistant le prend en charge.

Pour copier manuellement les fichiers dans votre projet, récupérez les compétences GitBook depuis le gitbook-skills dépôt.

Compétence	Description	Télécharger
configure-site	Créez et maintenez des sites complets de documentation GitBook.	GitHub
write-docs	Rédigez, créez, modifiez et mettez en forme des pages de documentation GitBook.	GitHub
write-openapi	Rédigez, configurez, structurez et dépannez la documentation de référence API OpenAPI/Swagger.	GitHub
build-integration	Créez des intégrations personnalisées pour GitBook.	GitHub
cr-create	Créez des demandes de changement GitBook, poussez du contenu, demandez des relectures et répondez aux commentaires.	GitHub
cr-review	Examinez les demandes de changement GitBook, résumez les modifications, commentez, approuvez ou demandez des modifications.	GitHub

N'oubliez pas de mettre à jour votre dépôt local avec le dernier fichier SKILL.md à mesure que GitBook ajoute de nouvelles fonctionnalités.

Utiliser les compétences GitBook

Scaffold a Git-synced docs site from a folder of markdown

Upgrade a plain markdown page into a polished GitBook page

Generate an API reference from an OpenAPI spec

FAQ

Que contient SKILL.md ?

fichier SKILL.md donne à votre assistant de code IA le contexte dont il a besoin pour créer, modifier et mettre en forme correctement le contenu GitBook.

Il inclut :

• Une référence complète de la syntaxe pour les blocs personnalisés.
• Les formats des fichiers de configuration, notamment .gitbook.yaml, SUMMARY.md, et .gitbook/vars.yaml.
• Les options de frontmatter, les contrôles de mise en page, les variables, les expressions, les tableaux de décision et les pièges courants.

Comment tester le contenu généré par l'IA ?

Vérifiez et testez toujours le contenu généré par des assistants IA. Lorsque vous travaillez avec un assistant entraîné sur le fichier de compétences :

• Vérifiez que les blocs personnalisés s'affichent correctement dans GitBook.
• Vérifiez que tous les liens internes fonctionnent.
• Confirmez que le frontmatter est un YAML valide.
• Testez que les variables font référence au bon périmètre.

Comment savoir si mon assistant utilise SKILL.md ?

Demandez-lui d'expliquer comment il mettrait en forme une page GitBook.

S'il fait référence aux blocs GitBook, au frontmatter, aux variables ou à des fichiers comme SUMMARY.md, la compétence est chargée.

S'il répond uniquement avec du Markdown générique, vérifiez les règles de votre projet et rechargez l'assistant.

Pourquoi l'assistant ignore-t-il la syntaxe spécifique à GitBook ?

Cela signifie généralement que le fichier de compétences n'est pas chargé, ou que les règles ne sont pas assez précises.

Assurez-vous que votre assistant lit fichier SKILL.md depuis la racine du dépôt, ou utilise l'URL GitHub dans les instructions de son projet.

Si l'assistant met les instructions en cache, redémarrez la session après avoir ajouté ou mis à jour la règle.

Que faire si l'assistant génère un contenu GitBook invalide ?

Vérifiez d'abord les points de défaillance courants :

• Blocs personnalisés non fermés
• YAML invalide dans le frontmatter
• Références de variables cassées
• Liens qui ne correspondent pas à la structure de vos pages

Vérifiez toujours le résultat dans GitBook avant de le valider.

Ai-je encore besoin d'un jeton d'accès ?

Vous avez besoin d'un jeton d'accès lorsque votre agent interagit directement avec GitBook. Vous pouvez créer un jeton d'accès personnel dans vos paramètres développeur.

Si vous modifiez uniquement des fichiers localement avec fichier SKILL.md, vous n'en aurez peut-être pas besoin tant que vous n'aurez pas connecté l'assistant aux workflows ou aux API GitBook.

Et si la compétence semble obsolète ?

Mettez à jour votre fichier SKILL.mdlocal, ou redirigez votre assistant vers la source GitHub.

Si votre équipe a copié des parties du fichier dans des règles personnalisées, mettez-les aussi à jour.