Créer un skill d’agent à partir d’un livre technique
Convertissez un PDF, un EPUB ou un dossier de docs internes en skill chargé à la demande : installation, budget de tokens, exécution headless et licence MIT.
Transformer un livre technique en compétence d’agent : ce que vous obtenez
Pour transformer un livre technique en compétence d’agent, vous fournissez à un convertisseur un PDF, un EPUB, un export DOCX ou un dossier de documents internes que vous possédez déjà. Il crée un répertoire de compétence : un fichier d’entrée contenant les frameworks nommés ainsi qu’un index des chapitres, et un fichier par chapitre que l’agent ne lit que si votre question le nécessite. Le livre n’entre jamais dans la fenêtre de contexte. Seul l’index y est chargé.
Cette tâche est à l’opposé de la création d’une compétence d’agent à partir de zéro, où vous encodez une procédure que vous connaissez déjà. Ici, les connaissances existent, mais personne ne peut y accéder : un PDF de fournisseur de 800 pages ou un manuel qui n’a pas été ouvert depuis le départ de la personne qui l’a rédigé. Le travail consiste à compresser et à indexer ces connaissances. Si le terme compétence vous est nouveau, lisez d’abord ce qu’est réellement une compétence d’agent.
Le convertisseur utilisé ici est book-to-skill, une compétence sous licence MIT qui s’exécute sur votre propre machine. Le tag actuel en octobre 2026 est v1.4.0. La structure qu’il produit compte davantage que l’outil lui-même, et la dernière section avant la FAQ montre comment créer cette même structure manuellement.
Pourquoi le budget de tokens détermine toute la conception
Un livre collé dans une fenêtre de contexte coûte sa taille complète à chaque conversation qui en a besoin. Une skill coûte une fois le contenu de son fichier d’entrée, puis uniquement les chapitres concernés par la question. Le projet définit un budget pour chaque fichier qu’il génère.
Les données de ce graphique
[
{
"label": "SKILL.md entry file",
"tokens": "4,000"
},
{
"label": "One chapter file",
"tokens": "1,000"
},
{
"label": "glossary.md",
"tokens": "1,500"
},
{
"label": "patterns.md",
"tokens": "2,000"
},
{
"label": "cheatsheet.md",
"tokens": "1,000"
}
]Le fichier d’entrée, SKILL.md, est limité à 4,000 tokens et contient les frameworks nommés ainsi que l’index des chapitres. Chaque fichier de chapitre contient environ 1,000 tokens et reste sur le disque jusqu’à ce qu’une requête le nécessite. Les fichiers complémentaires suivent le même principe : 1,500 tokens pour glossary.md, 2,000 pour patterns.md et 1,000 pour cheatsheet.md.
Ces budgets correspondent à la manière dont Claude Code utilise réellement le contexte. Le description d’une skill figure dans la liste des skills afin que le modèle sache que la skill existe. Le corps est chargé lorsque la skill est invoquée. Une fois chargé, il reste dans le contexte jusqu’à la fin de la session. Chaque ligne du fichier d’entrée représente donc un coût récurrent. Les fichiers complémentaires ne sont chargés que lorsque l’agent les lit, ce qui rend les fichiers séparés par chapitre économiques.
Une limite plus stricte se cache derrière cette valeur pour le fichier d’entrée. Lorsque l’auto-compaction résume une longue conversation, Claude Code rattache de nouveau la dernière invocation de chaque skill après le résumé. Il conserve les 5,000 premiers tokens de chacune, dans le cadre d’un budget combiné de 25,000 tokens pour toutes les skills rattachées. Un fichier d’entrée qui tient dans 5,000 tokens survit entièrement à la compaction. Un fichier d’entrée de 20,000 tokens revient avec son premier quart, sans aucune indication sur les trois quarts manquants.
C’est le progressive disclosure : un petit index dont le coût est toujours justifié, tandis que l’essentiel du contenu reste derrière une porte que l’agent ouvre volontairement. Comment Claude Code gère sa fenêtre de contexte présente le reste de ce calcul.
Installez le convertisseur sur votre VPS en le verrouillant sur une release
Le skill est un dépôt Git. Clonez-le dans le répertoire skills de l’agent que vous utilisez. Le nom du répertoire devient la commande slash. Le chemin de clonage n’est donc pas un choix anodin.
git clone --depth 1 --branch v1.4.0 \
https://github.com/virgiliojr94/book-to-skill.git \
~/.claude/skills/book-to-skill--branch accepte un tag. Cette commande extrait donc v1.4.0 et aucune version ultérieure. Verrouillez la version, car un skill est un ensemble d’instructions que votre agent suit. Une modification non vérifiée de ces instructions modifie ce qui s’exécute sur votre serveur. GitHub Copilot CLI lit plutôt ~/.copilot/skills/, et Amp lit ~/.agents/skills/.
Il existe également une installation en une ligne, npx skills add virgiliojr94/book-to-skill, qui récupère la version actuelle. Utilisez-la pour tester l’outil. Utilisez le clone verrouillé pour toute exécution ultérieure.
Vérifiez maintenant quels extracteurs sont disponibles sur le serveur :
cd ~/.claude/skills/book-to-skill
python3 scripts/extract.py --check--check indique quels extracteurs sont installés et affiche quoi installer pour ceux qui manquent : une commande pip combinée pour les paquets Python manquants et une indication pour chaque outil système absent. Le paquet nécessite Python 3.9 ou une version ultérieure.
Si /book-to-skill n’apparaît pas dans l’autocomplétion après le clonage, exécutez /reload-skills ou redémarrez votre agent. Claude Code surveille les répertoires de skills qui existaient au démarrage de la session. Un répertoire ~/.claude/skills/ créé il y a deux minutes n’est donc pas encore surveillé.
Quels extracteurs vous faut-il réellement ?
Rien n’est obligatoire en dehors de Python, car chaque format dispose d’un fallback dans la standard library. Ces fallbacks sont moins performants. Sur un petit serveur, le temps perdu vient surtout de l’installation d’extracteurs dont vous n’avez pas besoin.
pdftotext, fourni par le packagepoppler-utils, traite les PDF principalement composés de texte et s’exécute presque instantanément. Installez-le avecsudo apt install poppler-utils.pypdfetpdfminer.sixsont les fallbacks Python pour les PDF.doclingest destiné aux PDF techniques dont la valeur se trouve dans les tableaux et les listings de code. Le projet indique environ 1.5 secondes par page.ebooklibavecbeautifulsoup4lit correctement les fichiers EPUB. Sans eux, l’outil utilise le lecteurzipfilede la standard library.python-docxlit les fichiers DOCX etstriprtflit les fichiers RTF.- Le
ebook-convertde Calibre est nécessaire pour les fichiers MOBI et AZW. ocrmypdfeffectue l’OCR (reconnaissance optique de caractères) sur un livre numérisé qui ne contient aucune couche de texte.
Sur Ubuntu 24.04, un simple pip3 install pypdf s’arrête avec ceci :
error: externally-managed-environmentCe n’est pas un problème de pip. Ubuntu et Debian indiquent que le Python système est géré par apt. pip refuse donc d’y écrire. Deux solutions fonctionnent. sudo apt install poppler-utils installe un binaire et ne nécessite aucun pip, tandis que pdftotext suffit pour la plupart des PDF principalement composés de texte. Pour les extracteurs Python, créez un environnement virtuel et démarrez votre agent depuis cet environnement. Ainsi, le python3 appelé par la compétence est bien l’interpréteur qui contient les packages.
python3 -m venv ~/.venvs/book-to-skill
source ~/.venvs/book-to-skill/bin/activate
pip install "$HOME/.claude/skills/book-to-skill[pdf,epub,docx]"
claudeLe checkout v1.4.0 épinglé déclare les extras pdf, epub, docx, rtf, technical et all, où technical correspond à docling. La page d’installation du projet documente également une installation autonome en ligne de commande directement depuis GitHub, pip install "book-to-skill[pdf,epub,docx] @ git+https://github.com/virgiliojr94/book-to-skill.git", suivie de book-to-skill --check pour lister les extracteurs installés. Cette méthode ne nécessite aucune release PyPI. En revanche, elle installe la branche par défaut du projet au lieu de v1.4.0 et fournit uniquement la commande d’extraction, pas la compétence /book-to-skill. Pour une installation épinglée, installez le projet depuis votre propre checkout comme indiqué plus haut. Un simple pip install book-to-skill ne fonctionne pas, car ce nom n’est pas publié sur PyPI en date d’octobre 2026.
N’installez docling que lorsqu’un livre en a besoin. Ce package installe une stack de machine learning. Vérifiez donc l’espace disque disponible sur un petit plan avant de l’installer.
Exécuter la commande sur un dossier de documents, y compris sans interface interactive
La commande accepte un fichier, un dossier, un glob entre guillemets ou plusieurs chemins à la fois, suivis éventuellement d’un nom de skill. Vous pouvez fournir tout ce qui se trouve dans un même répertoire, y compris un ensemble de RFC (request for comments, les documents qui définissent les protocoles Internet).
/book-to-skill ~/library/platform-docs/ platform-handbook
/book-to-skill "~/books/*.epub" my-library
/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-researchMettez le glob entre guillemets pour que votre shell ne l’expanse pas avant que le skill le traite. Si vous indiquez un répertoire de skill existant, les nouvelles sources sont ajoutées à ce skill au lieu d’en créer un second.
Une exécution interactive vous pose plusieurs questions. Le contenu est-il technique ou principalement textuel ? Cette réponse détermine l’extracteur. Que doit vous aider à faire le skill ? Cette réponse définit le niveau de référence ou d’étude, ainsi que le budget par chapitre. Quel doit être le nom du skill et, s’il n’existe pas encore de skills root ou s’il y en a plusieurs, dans quel root doit-il être placé ? La commande affiche aussi une estimation du nombre de tokens et de la durée avant la génération, puis attend votre confirmation.
Une exécution sans interface interactive ne permet à personne de répondre à ces questions. Les skills invocables par l’utilisateur fonctionnent dans claude -p : placez la commande slash dans la chaîne d’invite, et Claude Code la développe avant le début de l’exécution. Répondez donc aux questions dans cette même invite.
claude -p "/book-to-skill ~/library/platform-docs/ platform-handbook
The sources are technical. Use reference depth. Write the skill to
~/.claude/skills/. Do not publish it to GitHub. Proceed without asking me." \
--allowedTools "Bash,Read,Write,Edit"--allowedTools préautorise les outils nécessaires à l’exécution, car une demande d’autorisation sans terminal attaché entraîne une exécution qui ne se termine jamais. Ajouter --output-format json inclut total_cost_usd dans le résultat. Il s’agit d’une estimation côté client, et non du montant facturé.
Avant toute lecture par le modèle, l’extraction regroupe chaque source dans un répertoire de travail temporaire sous /tmp. La dernière étape de l’exécution supprime ce répertoire. Si l’extraction d’une source échoue, celle-ci est ignorée afin que le traitement par lot continue. L’exécution peut donc signaler une réussite après avoir lu moins de fichiers que vous n’en avez fournis. Comparez l’inventaire des fichiers du rapport final avec le contenu du dossier. Un chapitre manquant indique généralement une source manquante.
Exécutez la commande sur un serveur que vous acceptez de mettre à la disposition d’un agent. Exécuter Claude Code en toute sécurité sur un VPS explique les aspects liés aux permissions.
Où la sortie est enregistrée pour que votre agent de programmation la trouve
La compétence générée est placée dans une racine de compétences. Deux emplacements sont importants.
~/.claude/skills/<skill-name>/est personnel et disponible dans tous les projets de cette machine..claude/skills/<skill-name>/se trouve dans un dépôt et est versionné avec lui.
Dans l’un ou l’autre, vous trouverez SKILL.md, un répertoire chapters/ contenant un fichier par chapitre, ainsi que les fichiers associés. Le nom du répertoire est la commande : ~/.claude/skills/platform-handbook/ vous donne donc /platform-handbook, que vous pouvez compléter par un sujet ou une question en langage courant.
Choisissez la racine en fonction de la licence, et non de la commodité. Une compétence créée à partir d’un livre que vous avez acheté appartient à votre répertoire personnel. Une compétence créée à partir de la documentation rédigée par votre équipe appartient au dépôt. Vous devez alors résoudre le problème suivant : partager une même compétence entre plusieurs dépôts.
Un coût augmente avec chaque compétence ajoutée. La description de chaque compétence reste dans la liste des compétences afin que le modèle puisse décider de l’utiliser. Le texte combiné des descriptions est tronqué à 1,536 caractères par entrée, et la liste entière dispose d’un budget limité. Dix compétences issues de livres signifient que dix descriptions se le disputent. Pour celles que vous appelez toujours par leur nom, ajoutez une ligne au frontmatter généré :
---
name: platform-handbook
description: Frameworks and chapter index from the internal platform handbook.
disable-model-invocation: true
---Avec disable-model-invocation: true, la description reste entièrement hors du contexte, et la compétence est tout de même chargée intégralement lorsque vous saisissez /platform-handbook. Vous renoncez à la découverte automatique, mais vous obtenez une fenêtre de contexte moins encombrée.
Licence : MIT couvre le convertisseur, pas le livre
Soyez précis sur ce point, car le problème n’est pas technique.
- La licence MIT couvre le code du convertisseur et la définition de sa skill. Elle ne dit rien sur le document que vous lui fournissez.
- Exécuter le convertisseur sur un livre que vous avez acheté, avec du matériel que vous contrôlez, revient à prendre des notes à partir de votre propre exemplaire.
- Publier le résultat constitue une distribution. La licence MIT de l’outil ne vous accorde aucun droit de distribuer quoi que ce soit dérivé du livre de quelqu’un d’autre.
- Le résultat est une œuvre dérivée. Les frameworks et les synthèses des chapitres restent façonnés par la source, et une œuvre dérivée reste régie par le copyright de la source.
- Une skill créée à partir d’un contenu que vous ne pouvez pas redistribuer reste sur la machine qui l’a créée. Elle ne doit pas être publiée dans un dépôt public ni dans une marketplace partagée par l’équipe.
- Publiez lorsque la source vous appartient ou qu’elle est distribuée sous une licence ouverte : documentation rédigée par votre équipe ou norme dont les conditions autorisent la redistribution.
L’outil est conçu dans cette optique. Il ne fournit aucun contenu de livre et l’extraction s’exécute localement. Le marqueur v1.4.0 affiche uniquement une ligne gh skill publish facultative et ne pose jamais de question sur la visibilité. La décision vous revient donc entièrement. La branche par défaut du projet a depuis ajouté une étape de publication qui demande la visibilité du dépôt dans une question distincte, avec une seule réponse d’un mot, et qui ne crée un dépôt public que si la réponse est exactement public. Toute autre réponse produit un dépôt privé. Considérez cette étape comme la décision de licence, car c’est bien ce qu’elle représente.
Les manuels internes posent un second problème. Ils contiennent plus souvent des identifiants que personne ne veut l’admettre, et un convertisseur transforme un PDF que personne n’ouvre en fichier que votre agent lit à la demande. Lisez les fichiers générés une fois avant de les valider, puis consultez éviter de laisser des secrets dans vos agents IA.
Quel est le coût d’une conversion ?
Les chiffres ci-dessous sont les mesures publiées par le projet, et non les nôtres.
Les données de ce graphique
[
{
"label": "Think Python 2",
"cost_usd": 0.88
},
{
"label": "Working Backwards",
"cost_usd": 0.96
},
{
"label": "Pro Git",
"cost_usd": 1.23
},
{
"label": "Moby-Dick",
"cost_usd": 1.42
}
]Pour les 4 livres mesurés par le projet, une conversion coûte entre 0.88 et 1.42 dollars américains, avec Pro Git à 1.23. Les mesures ont été réalisées avec Claude Sonnet 4.5, à partir des nombres de tokens de tiktoken obtenus avec cl100k_base. Elles sont publiées dans le docs/performance.md du projet en octobre 2026. Votre propre montant dépend du modèle utilisé et de vos tarifs.
Le projet indique également qu’il faut 24 à 51 fois moins de tokens pour répondre à une question à partir de la skill que depuis l’intégralité du livre collée dans le contexte. Considérez cela comme l’ordre de grandeur de l’économie, et non comme une garantie, car le résultat dépend du livre et de la question. Le principe structurel reste le même : la conversion est payée une seule fois, tandis qu’un dump du contexte est payé à nouveau pour chaque conversation qui nécessite le livre.
Pourquoi ne pas coller le PDF ou créer un index RAG ?
Le collage fonctionne et constitue la bonne solution pour une question portant sur un seul document. Il cesse de l’être lorsque vous avez besoin du même livre le mardi, puis de nouveau le vendredi, car vous payez sa taille complète à chaque fois.
La recherche documentaire, ou RAG (retrieval augmented generation), effectue une recherche au moment de la requête et renvoie les passages qui correspondent à vos mots. Cette approche est efficace lorsque vous avez besoin de la phrase exacte. Elle l’est moins lorsque l’information utile est un cadre réparti sur un chapitre, car aucun passage unique ne le contient entièrement. Une skill effectue cette extraction une seule fois, au moment de la conversion, et stocke la structure plutôt que les passages.
La limite est claire : une skill générée est un résumé avec perte, rédigé par un modèle. Elle sert d’aide à l’étude, mais la source reste la source. Lorsque la formulation exacte a une portée juridique ou protocolaire, conservez le PDF et citez-le. Comparaison des skills, des serveurs MCP et des fichiers de règles explique dans quels cas chaque approche convient.
Modes d’échec et messages affichés
Un PDF numérisé ne produit aucune sortie. L’extracteur vérifie la présence d’une couche de texte dans les premières pages, puis s’arrête en expliquant le problème au lieu de traiter péniblement 400 pages d’images. Exécutez d’abord ocrmypdf input.pdf output.pdf, puis fournissez-lui le fichier de sortie.
pip refuse l’installation. error: externally-managed-environment sur Ubuntu 24.04 correspond à la protection du Python système par apt. Utilisez l’environnement virtuel indiqué plus haut, ou installez poppler-utils et ignorez complètement pip.
Les chapitres sont incorrects. La détection des chapitres recherche des titres explicites tels que Chapter 7 et leurs variantes linguistiques. Elle reconnaît aussi les chiffres romains comme Chapter IV ou IV. Title. Un livre qui utilise des titres de section seuls et non numérotés produit un découpage incorrect. Pour corriger le problème, indiquez au lancement où commencent les chapitres au lieu de compter sur une détection automatique.
La commande n’existe pas. Si /book-to-skill n’apparaît pas dans l’autocomplétion, le répertoire des skills a été créé après le début de votre session. Exécutez /reload-skills ou redémarrez l’agent.
Docling prend beaucoup de temps. À environ 1.5 seconde par page, le traitement d’un livre volumineux consomme plusieurs minutes de temps CPU. Sur un serveur partagé, il concurrence les autres services que vous hébergez. Répondez « text-heavy » lorsque le lancement vous demande le type de contenu, ou transmettez --mode text si vous exécutez vous-même scripts/extract.py. --mode technical est la réponse qui sélectionne docling.
Une source disparaît sans message. Un fichier illisible est ignoré pour permettre au traitement par lots de se terminer. Le lancement indique alors une réussite pour un nombre de sources inférieur à celui que vous avez fourni. Le seul endroit où cette différence apparaît est l’inventaire des fichiers dans le rapport final. Vérifier un traitement terminé par rapport aux éléments réellement fournis est une bonne pratique applicable bien au-delà de cet outil. La méthode Depth Tree du skill unlazy permet notamment d’imposer cette vérification à un agent, au lieu de le laisser déclarer prématurément le travail terminé.
Appliquez le même modèle manuellement
L’outil est un utilitaire. La structure est la partie transférable, et un éditeur de texte permet de la créer pour toute documentation de référence dont vous disposez.
- Rédigez un fichier d’entrée et maintenez-le autour de 4,000 tokens, comme le vise le convertisseur. Ajoutez-y les concepts nommés avec leur formulation exacte, ainsi qu’un index répertoriant chaque fichier de détail et les sujets qu’il contient.
- Divisez la documentation en fichiers d’environ 1,000 tokens, à raison d’un sujet par fichier. Nommez-les de façon que le nom du fichier indique à lui seul son contenu.
- Décrivez chacun de ces fichiers dans le fichier d’entrée, dans la phrase qui indique quand le consulter.
L’étape 3 est celle que l’on omet le plus souvent. C’est aussi celle qui permet au modèle de fonctionner. L’agent choisit les fichiers à ouvrir en lisant l’index. Un fichier que l’index ne décrit pas est donc un fichier que l’agent n’ouvre jamais. L’index est le produit, et les fichiers de chapitres servent de stockage.
Conservez le fichier d’entrée dans la limite du budget de compaction afin que toute la structure reste exploitable pendant une longue session. Cette règle s’applique que les fichiers aient été créés par un convertisseur ou par vous.
FAQ
Puis-je publier une skill créée à partir d’un livre que j’ai acheté ?
Non, sauf si la licence de ce livre autorise sa redistribution. La licence MIT du convertisseur couvre le code du convertisseur, pas le contenu que vous lui fournissez, et la skill générée est une œuvre dérivée du livre. Conservez-la dans ~/.claude/skills/ sur votre propre machine. Vous pouvez publier la documentation que vous avez rédigée vous-même ou des sources distribuées sous une licence libre. Le v1.4.0 épinglé ne demande jamais si elle est visible, tandis que la branche par défaut du projet pose maintenant cette question séparément et ne la rend publique que pour une valeur exacte de public. Dans les deux cas, vous devez donc prendre cette décision délibérément.
Ai-je besoin de docling, ou pdftotext suffit-il ?
pdftotext de poppler-utils suffit pour le texte courant et son exécution est presque instantanée. Installez docling si la valeur du livre se trouve dans ses tableaux et ses exemples de code, car un extracteur de texte brut supprime précisément ces éléments. Le compromis concerne la vitesse : le projet mesure docling à environ 1.5 seconde par page. Un manuel de 300 pages demande donc plusieurs minutes de temps CPU sur un VPS.
Pourquoi pip échoue-t-il avec externally-managed-environment sur mon VPS ?
Ubuntu 24.04 et les versions actuelles de Debian indiquent que le Python système est géré par apt. pip refuse donc de s’y installer et affiche error: externally-managed-environment. Créez un environnement virtuel avec python3 -m venv ~/.venvs/book-to-skill, activez-le, installez-y les extracteurs, puis démarrez votre agent depuis ce même shell. La skill appelle python3. Elle utilise donc l’interpréteur présent dans votre PATH, qui est maintenant celui de l’environnement virtuel.
Pourquoi ma skill générée n’apparaît-elle pas comme commande slash ?
Deux causes sont possibles. Le nom de la commande provient du nom du répertoire. La skill doit donc se trouver dans ~/.claude/skills/<name>/SKILL.md ou .claude/skills/<name>/SKILL.md, avec SKILL.md écrit exactement de cette manière. Si le chemin est correct, exécutez /reload-skills ou redémarrez l’agent. Claude Code détecte les modifications effectuées dans les répertoires de skills qu’il surveille déjà. En revanche, il ne surveille pas un répertoire de skills créé après le démarrage de la session tant que vous n’avez pas effectué cette opération.