Créer un skill d’agent à partir d’un livre technique

Transformer un ouvrage technique en skill d’agent : ce que vous obtenez

Pour transformer un ouvrage technique en skill 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 skill : 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 rédaction d’un skill d’agent à partir de zéro, qui consiste à encoder 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 le contenu. Si le terme skill ne vous est pas familier, lisez d’abord ce qu’est réellement un skill d’agent.

Le convertisseur utilisé ici est book-to-skill, un skill sous licence MIT qui s’exécute sur votre propre machine. Le tag actuel en août 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.

[
  {
    "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.

Installer 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 des skills de l’agent que vous utilisez. Le nom du répertoire devient la slash command : 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 récupère 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 aussi une installation en une ligne, npx skills add virgiliojr94/book-to-skill, qui récupère la version courante. Utilisez-la pour tester l’outil. Pour toute nouvelle exécution, utilisez le clone verrouillé sur une version précise.

Vérifiez maintenant quels extractors sont présents sur le serveur :

cd ~/.claude/skills/book-to-skill
python3 scripts/extract.py --check

--check indique quels extractors sont installés et affiche la commande d’installation de chaque extractor manquant. Le package 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, redémarrez votre agent. Claude Code surveille les répertoires de skills qui existaient au démarrage de la session. Un ~/.claude/skills/ créé il y a deux minutes n’est donc pas encore surveillé.

De quels extracteurs avez-vous réellement besoin ?

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 paquet poppler-utils, traite les PDF riches en texte et est presque instantané. Installez-le avec sudo apt install poppler-utils.
• pypdf et pdfminer.six sont les fallbacks Python pour les PDF.
• docling est destiné aux PDF techniques dont l’intérêt se trouve dans les tableaux et les listings de code. Le projet indique environ 1.5 seconde par page.
• ebooklib avec beautifulsoup4 lit correctement les fichiers EPUB. Sans eux, l’outil utilise le reader zipfile de la standard library.
• python-docx lit les fichiers DOCX et striprtf lit les fichiers RTF.
• Le ebook-convert de Calibre est requis pour les fichiers MOBI et AZW.
• ocrmypdf effectue 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 le message suivant :

error: externally-managed-environment

Ce n’est pas un problème de pip. Ubuntu et Debian marquent le Python système comme étant 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 pas pip. pdftotext suffit à lui seul pour la plupart des PDF contenant principalement du texte. Pour les extracteurs Python, créez un environnement virtuel et démarrez votre agent depuis cet environnement. Ainsi, le python3 appelé par la skill est bien l’interpréteur qui contient les paquets.

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]"
claude

Le repository déclare les extras pdf, epub, docx, rtf, technical et all, où technical correspond à docling. La page d’installation du projet indique également pip install "book-to-skill[pdf,epub,docx]", mais ce nom n’est pas publié sur PyPI en août 2026. Installez-le donc depuis votre propre checkout, comme ci-dessus.

Laissez docling de côté jusqu’à ce qu’un livre en ait besoin. Il installe une stack de machine learning. Vérifiez donc l’espace disque disponible avant de l’installer sur une petite offre.

Exécuter la commande sur un dossier de documents, y compris sans interface

La commande accepte un fichier, un dossier, un glob entre guillemets ou plusieurs chemins à la fois, suivis éventuellement du nom d’une skill. Tout ce que vous pouvez placer dans un même répertoire fonctionne, 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-research

Mettez le glob entre guillemets afin que votre shell ne l’étende pas avant que la skill le traite. Si vous indiquez le chemin d’un répertoire de skill existant, les nouvelles sources sont ajoutées à cette skill au lieu d’en créer une seconde.

Une exécution interactive vous pose plusieurs questions. Le contenu est-il technique ou principalement textuel ? Cela détermine l’extracteur. Voulez-vous une profondeur de référence ou d’étude ? Cela détermine le budget associé à chaque chapitre. Quel nom donner à la skill, et dans quelle skills root l’installer ? La commande affiche également 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 n’a personne pour répondre à ces questions. Les skills invocables par l’utilisateur fonctionnent dans claude -p : placez la slash command dans la chaîne du prompt et Claude Code la développe avant le début de l’exécution. Répondez donc aux questions dans le même prompt.

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 approuve à l’avance les outils nécessaires à l’exécution, car une demande d’autorisation sans terminal associé bloque l’exécution. Ajouter --output-format json insère total_cost_usd dans le résultat. Il s’agit d’une estimation côté client, qui ne correspond pas à votre facturation.

L’extraction regroupe chaque source dans un répertoire de travail temporaire sous /tmp avant toute lecture par le modèle. 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 lots puisse continuer. L’exécution peut donc signaler une réussite alors qu’elle a 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 correspond généralement à une source manquante.

Exécutez la commande sur un serveur que vous êtes prêt à confier à un agent. Exécuter Claude Code en toute sécurité sur un VPS traite l’aspect lié 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.

Licensing : la 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 sa définition de compétence. 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 un contenu 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 les droits d’auteur attachés à cette source.
• Une compétence 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 uniquement lorsque la source vous appartient ou 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 contient aucun livre, l’extraction s’effectue localement et son étape de publication demande séparément la visibilité du dépôt. Elle accepte uniquement le mot exact public ou private, sans en déduire une valeur. Considérez cette invite 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 une fois les fichiers générés avant de les valider, puis consultez garder les secrets hors de 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.

[
  {
    "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ûtait entre 0.88 et 1.42 dollars américains, avec Pro Git à 1.23. Les mesures ont été effectuées avec Claude Sonnet 4.5, à partir des nombres de tokens fournis par tiktoken avec cl100k_base. Elles sont publiées dans docs/performance.md du projet, en date d’août 2026. Votre propre montant varie selon votre modèle et vos tarifs.

Le projet indique également qu’il faut 24 à 51 fois moins de tokens pour répondre à une question à partir du skill que pour répondre à partir du livre entier copié dans le contexte. Considérez ce chiffre comme l’ordre de grandeur de l’économie réalisée, et non comme une garantie, car le résultat dépend du livre et de la question. Le principe structurel reste valable : 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 aucun résultat. L’extracteur vérifie la présence d’une couche de texte dans les premières pages. S’il n’en trouve pas, il s’arrête en affichant une explication au lieu de traiter laborieusement 400 pages d’images. Exécutez d’abord ocrmypdf input.pdf output.pdf, puis transmettez-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 présenté plus haut, ou installez poppler-utils et n’utilisez pas pip.

Les chapitres sont mal détectés. La détection recherche des headings explicites tels que Chapter 7 et leurs variantes selon la langue. Un livre qui utilise de simples titres de section ou des chiffres romains produit un découpage incorrect. Pour corriger le problème, indiquez au lancement où commencent les chapitres au lieu de laisser l’outil le deviner.

La commande n’existe pas. Si /book-to-skill n’apparaît pas dans l’autocomplétion, cela signifie que le skills directory a été créé après le début de votre session. Redémarrez l’agent.

Docling prend beaucoup trop de temps. À environ 1.5 seconde par page, le traitement d’un livre volumineux consomme plusieurs minutes de temps CPU. Sur un serveur partagé, ce traitement entre en concurrence avec les autres services hébergés. Répondez « text-heavy » lorsque le lancement vous demande le type de contenu, ou transmettez --mode text lorsque vous pilotez 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 traitement indique alors une réussite pour un nombre de sources inférieur à celui que vous avez fourni. Seul l’inventaire des fichiers dans le rapport final permet de le constater.

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.

1. 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.
2. 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.
3. 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 de la documentation que vous avez rédigée vous-même ou provenant de sources sous licence libre. L’outil demande aussi séparément la visibilité du repository et n’accepte qu’un simple public ou private. La décision reste donc explicite.

Ai-je besoin de docling, ou pdftotext suffit-il ?

pdftotext de poppler-utils suffit pour la prose et son exécution est presque instantanée. Installez docling lorsque les tableaux et les extraits de code sont essentiels dans le livre, car un extracteur de texte brut les ignore précisément. 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 d’y installer des paquets 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 désormais 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 vient 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, redémarrez l’agent. Claude Code détecte les modifications dans les répertoires de skills qu’il surveille déjà, mais un répertoire de skills créé après le démarrage de la session n’est pas surveillé.