Convertisseur Book-to-Skill

Transformez la connaissance écrite en compétences actionnables pour les agents en extrayant la structure — sans produire de résumés.

Philosophie

Les livres contiennent une expertise cristallisée : des frameworks, des principes et des techniques qui ont nécessité des années de développement. Cette compétence extrait cette connaissance dans un format que GitHub Copilot CLI, Amp, Claude Code ou un autre agent compatible peut exploiter de manière répétée.

Extrayez la structure, pas les résumés. Une compétence n'est pas un compte rendu de lecture. C'est une boîte à outils comprenant :

Des frameworks nommés (modèles mentaux avec une application claire)
Des principes actionnables (règles qui guident les décisions)
Des techniques (méthodes étape par étape)
Des anti-patrons (ce qu'il faut éviter et pourquoi)
Un calibrage vocal (comment l'auteur pense et communique)

Préservez la précision de l'auteur. Les frameworks ont souvent des noms spécifiques pour une raison. « Les 5 Pourquoi » n'est pas interchangeable avec « demander pourquoi plusieurs fois ». Capturez la formulation exacte.

Adaptez la profondeur de manière appropriée. Livres simples → compétences simples. Livres complexes avec 10+ frameworks → compétences avec fichiers de référence et chapitres à la demande.

Modes de fonctionnement

Quatre chemins disponibles. Acheminez en fonction de ce que l'utilisateur demande :

1. Conversion complète (par défaut)

Déclencheur : L'utilisateur fournit un ou plusieurs chemins de document/répertoire/glob sans instructions spéciales Action : Exécute toutes les étapes ci-dessous (Étapes 0 à 9) Sortie : Compétence complète avec SKILL.md, chapitres/, glossaire, modèles, antisèche

2. Analyse uniquement

Déclencheur : L'utilisateur dit « analyse », « juste extraire » ou « je veux vérifier avant de générer » Action : Exécute les Étapes 0 à 3, puis produit un rapport d'extraction structuré (frameworks, principes, techniques trouvés). Arrêtez-vous — NE générez PAS de fichiers de compétence. Sortie : Rapport d'analyse pour l'examen par l'utilisateur

3. Générer à partir d'une analyse existante

Déclencheur : L'utilisateur dispose de notes d'analyse existantes ou a précédemment exécuté une analyse uniquement Action : Saute les Étapes 0 à 3, utilise l'analyse fournie comme entrée, exécute les Étapes 4 à 9 Sortie : Fichiers de compétence à partir de l'analyse fournie

4. Mettre à jour / Intégrer (Compétence existante)

Déclencheur : L'utilisateur fournit un ou plusieurs nouveaux chemins source et indique qu'il souhaite mettre à jour une compétence existante (soit en pointant vers le dossier de la compétence existante, en fournissant un slug de compétence qui existe déjà dans SKILLS_HOME, ou en demandant explicitement une mise à jour). Action : Exécute l'Étape 0 (vérification hors périmètre), l'Étape 1 (valider les entrées), l'Étape 1.5 (identifier le type de livre), et l'Étape 2 (extraire les nouveaux fichiers). Saute ensuite à l'Étape 5 (identifier/détecter le chemin de la compétence existante) et exécute le Workflow de mise à jour / d'intégration pour fusionner le nouveau contenu dans les fichiers de compétence existants. Sortie : Compétence existante mise à jour avec des résumés de chapitres nouveaux/révisés et des index/glossaires fusionnés.

Emplacements des compétences

Ce convertisseur peut être exécuté à partir de plusieurs systèmes de compétences. Lorsque vous recherchez le script d'aide de ce convertisseur ou que vous écrivez la compétence de livre générée, privilégiez ces emplacements dans l'ordre :

Compétences personnelles GitHub Copilot CLI : ~/.copilot/skills/
Compétences personnelles multi-agents (Copilot + Amp) : ~/.agents/skills/
Compétences personnelles Claude Code : ~/.claude/skills/
Compétences Copilot locales au projet : .github/skills/
Compétences Claude locales au projet : .claude/skills/
Compétences Amp / Copilot locales au projet : .agents/skills/
Compétences Amp globales : ~/.config/agents/skills/
Compétences Amp globales héritées : ~/.config/amp/skills/

Pour les compétences de livre générées, choisissez une destination que l'agent hôte de l'utilisateur peut réellement découvrir (voir Étape 5). Lorsque plusieurs racines valides existent, demandez à l'utilisateur une fois et mémorisez la réponse pour la session — ne choisissez pas silencieusement par défaut.

Étape 0 — Vérification hors périmètre

Si aucun argument n'est fourni, arrêtez-vous et répondez :

« book-to-skill nécessite un chemin de document pris en charge, un dossier ou un modèle glob. Utilisation : book-to-skill <chemin-vers-dossier-de-documents-ou-glob>... [slug-nom-compétence] »

Tout au long du workflow :

Identifiez les chemins d'entrée et le slug de compétence optionnel.
Si le dernier argument n'est pas un fichier, un dossier ou un glob qui existe ou correspond à des fichiers, et qu'il ressemble à un slug de compétence (par ex. minuscules avec traits d'union, alphanumérique), traitez-le comme SKILL_NAME.
Traitez tous les autres arguments comme la liste des INPUT_PATHS.
Si un chemin d'entrée est un répertoire de compétence existant (contient SKILL.md et un sous-dossier chapters/), ou si SKILL_NAME correspond à un slug de compétence existant dans SKILLS_HOME, marquez cette exécution comme une opération de Mise à jour / Intégration (Mode 4).

Étape 1 — Valider l'entrée

Vérifiez qu'il y a au moins un fichier, répertoire ou modèle glob pris en charge parmi les INPUT_PATHS. Pour les répertoires et les globs, développez-les pour trouver les fichiers pris en charge correspondants (.pdf, .epub, .docx, .txt, .md, .markdown, .rst, .adoc, .html, .htm, .rtf, .mobi, .azw, .azw3).

Si aucun fichier pris en charge n'est trouvé, arrêtez-vous avec un message d'erreur clair.

Étape 1.5 — Identifier le type de contenu

Avant l'extraction, demandez à l'utilisateur :

« Quel type de contenu ces sources ont-elles ? Cela m'aide à choisir la meilleure méthode d'extraction.

Technique — contient des blocs de code, des tableaux, des formules, des diagrammes (par ex. livres de programmation, articles académiques, guides d'architecture)

Principalement du texte — surtout de la prose, peu ou pas de tableaux/code (par ex. gestion, productivité, non-fiction narrative)

Pas sûr — j'utiliserai la méthode rapide et vous avertirai si la qualité semble limitée »

Stockez la réponse comme BOOK_TYPE :

Option 1 → BOOK_TYPE=technical
Option 2 → BOOK_TYPE=text
Option 3 → BOOK_TYPE=text

Si BOOK_TYPE=technical, informez l'utilisateur avant de continuer :

« 📐 Mode technique sélectionné — utilisation de Docling pour une extraction sensible à la structure (tableaux, blocs de code, formules préservés en markdown). Cela prend ~1,5 s par page, donc attendez-vous à quelques minutes pour les sources plus longues. Démarrage maintenant… »

Si BOOK_TYPE=text, informez :

« 📄 Mode texte sélectionné — utilisation de l'extracteur le plus rapide adapté à chaque type de fichier. Le texte brut/Markdown/HTML sont généralement prêts en quelques secondes ; les PDF utilisent pdftotext lorsqu'il est disponible. »

Étape 2 — Extraire le texte des documents sources

Exécutez le script d'extraction, en passant les chemins d'entrée :

SCRIPT_PATH=""
for candidat in \
  "$HOME/.copilot/skills/book-to-skill/scripts/extract.py" \
  "$HOME/.agents/skills/book-to-skill/scripts/extract.py" \
  "$HOME/.claude/skills/book-to-skill/scripts/extract.py" \
  ".github/skills/book-to-skill/scripts/extract.py" \
  ".claude/skills/book-to-skill/scripts/extract.py" \
  ".agents/skills/book-to-skill/scripts/extract.py" \
  "$HOME/.config/agents/skills/book-to-skill/scripts/extract.py" \
  "$HOME/.config/amp/skills/book-to-skill/scripts/extract.py"
faire
  if [ -f "$candidat" ]; alors
    SCRIPT_PATH="$candidat"
    casser
  fi
fait

if [ -z "$SCRIPT_PATH" ]; alors
  echo "Impossible de trouver scripts/extract.py pour book-to-skill" >&2
  sortie 1
fi

PYTHON_BIN="${PYTHON_BIN:-python3}"
if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; alors
  PYTHON_BIN="python"
fi

"$PYTHON_BIN" "$SCRIPT_PATH" $INPUT_PATHS --mode <BOOK_TYPE> --install-missing ask

Avant l'extraction, le script vérifie les paquets Python optionnels nécessaires pour le format détecté. Si un meilleur extracteur manque, il invite l'utilisateur avec le repli disponible. Les sessions non interactives utilisent le repli par défaut sauf si le mode d'installation est explicitement yes.

Astuce — vérifier l'environnement : exécutez "$PYTHON_BIN" "$SCRIPT_PATH" --check pour imprimer un rapport par format indiquant quels extracteurs sont installés et la commande exacte pour installer ce qui manque, sans traiter aucun fichier. Utile lorsqu'un utilisateur signale un problème de configuration ou de qualité.

Cela crée :

<tempdir>/book_skill_work/full_text.txt — texte extrait combiné de toutes les sources avec des limites visuellement claires.
<tempdir>/book_skill_work/metadata.json — taille totale combinée, mots, pages, nombre de tokens, et une liste détaillée des sources individuelles traitées.

Lisez <tempdir>/book_skill_work/metadata.json pour inspecter les résultats.

Étape 2.5 — Estimation préliminaire du coût

Lisez <tempdir>/book_skill_work/metadata.json et présentez à l'utilisateur une estimation avant toute génération :

📖 Sources détectées : <total_sources> source(s)
<listez chaque nom de fichier source et format à partir de la liste de métadonnées des sources>
📄 Pages/Sections combinées : ~<N> | Mots : ~<N> | Tokens totaux : ~<N>K

💰 Coût estimé en tokens (Conversion complète / Mise à jour) :
   Entrée (lecture + invites) : ~<N>K tokens
   Sortie (fichiers de compétence générés/mis à jour) :  ~<N>K tokens
   Total :                           ~<N>K tokens

   Coût : multipliez les nombres de tokens ci-dessus par les tarifs actuels d'entrée/sortie
   par million de tokens de votre modèle (les prix et les noms de modèle changent souvent —
   ne les codez pas en dur ; citez le tarif d'aujourd'hui et étiquetez-le comme une estimation).

   ⏱  Temps estimé : ~<N> minutes

📁 Fichiers à générer/mettre à jour :
   SKILL.md + fichiers de chapitres + glossaire + modèles + antisèche

➡  Procéder à la Conversion complète / Mise à jour ? (ou tapez « analyse uniquement » pour prévisualiser d'abord)

Comment estimer :

Tokens d'entrée ≈ estimated_tokens des métadonnées × 1,3 (surcharge des invites par passage de chapitre)
Tokens de sortie ≈ chapitres × budget par chapitre + 4 000 (SKILL.md) + 4 500 (glossaire + modèles + antisèche)
- Budget médian par chapitre selon BOOK_TYPE (PROFONDEUR est décidée plus tard à l'Étape 4 et peut l'augmenter) : text ≈ 1 000, technical ≈ 1 800. Si l'utilisateur a déjà indiqué référence uniquement vs étude approfondie, utilisez la ligne correspondante de la matrice de l'Étape 7.
Coût : rapportez les nombres de tokens et multipliez par les tarifs d'entrée/sortie par million de tokens actuels de l'utilisateur. Ne codez PAS les montants en dollars — les noms et les prix des modèles changent ; si vous en affichez un, étiquetez-le comme une estimation et datez-le.

Attendez que l'utilisateur confirme avant de continuer. S'il dit « analyse uniquement », passez au Mode 2.

Étape 2.6 — Accès de type REPL pour les grands livres (> 50k tokens)

Inspiré du paradigme Recursive Language Model (RLM) : traitez full_text.txt comme un corpus interrogeable, pas comme une seule lecture. Charger l'intégralité du fichier dans le contexte brûle le budget dont vous aurez besoin plus tard pour la génération.

Pour les livres de plus de ~50k tokens, privilégiez les sondes programmatiques plutôt que Read(full_text.txt) sans limites :

# Vérification de taille avant toute lecture
wc -w "$FULL_TEXT_PATH"

# Trouver les décalages de chapitres sans charger l'intégralité du fichier
grep -n -E "^\s*(Chapter|CHAPTER|Chapitre)\s+[0-9]+" "$FULL_TEXT_PATH" | head -40

# Extraire uniquement le chapitre dont vous avez besoin (lignes début..fin inclusives)
sed -n '<début>,<fin>p' "$FULL_TEXT_PATH"

# Vérifier qu'un framework est effectivement mentionné avant de le revendiquer dans SKILL.md
grep -c -i "westrum\|dora" "$FULL_TEXT_PATH"

# Lecture ciblée avec décalage/limite évite de vider le fichier complet
# Read(file_path=full_text.txt, offset=<ligne>, limit=<lignes>)

Utilisez cette approche pour l'Étape 3 (analyse de structure), l'Étape 7 (résumés par chapitre), et l'Étape 8 (extraction de glossaire / modèles). Pour les livres de moins de 50k tokens, une seule Read convient.

Pourquoi c'est important : un livre de 200 pages fait ~75k tokens. Le relire une fois par chapitre (28 passes) coûte ~2M tokens d'entrée ; utiliser grep + sed pour extraire uniquement les tranches pertinentes maintient le coût de génération proportionnel à la sortie, pas à la source.

Étape 3 — Analyser la structure du livre

Lisez les 8 000 premiers caractères du full_text.txt extrait pour identifier :

Le titre du livre et le(s) auteur(s)
La structure des chapitres (cherchez « Chapitre N », « PARTIE I », titres numérotés, table des matières)
Les thèmes principaux et le domaine du sujet
Le nombre approximatif de chapitres

Lisez ensuite la section Table des matières si présente pour cartographier tous les chapitres.

Si le mode est « Analyse uniquement » : produisez maintenant le rapport d'extraction et arrêtez-vous. Structure :

## Rapport d'extraction — <Titre>

### Frameworks principaux de l'auteur
- **<Nom du framework>** : <ce que c'est et quand l'appliquer>

### Principes clés
- <Principe> : <règle actionnable>

### Techniques et méthodes
- <Technique> : <étape par étape ou mode d'emploi>

### Anti-patrons
- <Ce qu'il faut éviter> : <pourquoi>

### Nom de compétence suggéré
`{nom-auteur}-{concept-central}` — par ex. `cialdini-influence`

### Chapitres détectés
| # | Titre | Frameworks principaux |

Étape 4 — Demander l'objectif (Conversion complète uniquement)

Avant de générer, demandez à l'utilisateur :

« Que devrait vous aider à faire cette compétence ? (Choisissez une ou plusieurs options)

Appliquer les frameworks de l'auteur pendant le travail

Penser avec les modèles mentaux de l'auteur

Référencer des chapitres et concepts spécifiques

Tout ce qui précède »

Utilisez la réponse pour pondérer ce qui est mis en évidence dans la section Core du SKILL.md.

Déduisez PROFONDEUR de la réponse (pas d'invite supplémentaire) :

La réponse est uniquement l'option 3 (référence) → PROFONDEUR=reference — chapitres légers, à consultation rapide.
La réponse inclut l'option 1, 2 ou 4 → PROFONDEUR=study — chapitres plus profonds avec plus de détails travaillés, d'exemples et de raisonnements.

PROFONDEUR et BOOK_TYPE ensemble définissent le budget de tokens par chapitre à l'Étape 7. Ne posez pas de question séparée « étude vs référence » — elle est déduite ici. (Dans les Modes 2/3, où l'Étape 4 est sautée, PROFONDEUR=study par défaut.)

Étape 5 — Déterminer le nom de la compétence

Si SKILL_NAME a été fourni, utilisez-le comme slug de la compétence. Sinon, proposez deux options et laissez l'utilisateur choisir :

Par auteur-concept : {nom-auteur}-{concept-central} (par ex. cialdini-influence, meadows-systems)
Par titre : minuscules avec traits d'union à partir du titre du livre (par ex. designing-data-intensive-apps)

Par défaut, privilégiez le format auteur-concept si le livre a une forte identité méthodologique.

Choisissez la racine de destination de la compétence (SKILLS_HOME). Sondez le système de fichiers de l'utilisateur pour les domiciles de compétences existants et choisissez en fonction de l'hôte que l'utilisateur utilise actuellement :

| Agent hôte | Personnel

...

[Contenu tronqué pour la traduction]

Leutenegger/book-to-skill

Qu'est-ce que book-to-skill ?

Demander à votre IA préférée

Documentation