virgiliojr94/book-to-skill

Convertisseur Livre-vers-Compétence

Transformez le savoir écrit en compétences actionnables pour agents en extrayant la structure — pas en produisant des résumés.

Philosophie

Les livres contiennent une expertise cristallisée : des frameworks, des principes et des techniques qui ont pris des années à se développer. Cette compétence extrait ce savoir dans un format que GitHub Copilot CLI, Amp, Claude Code, Hermes Agent, ou un autre agent compatible peut exploiter de manière répétée.

Extraire la structure, pas les résumés. Une compétence n'est pas un rapport de livre. C'est une boîte à outils de :

• Frameworks nommés (modèles mentaux avec application claire)
• Principes actionnables (règles qui guident les décisions)
• Techniques (méthodes pas-à-pas)
• Anti-patrons (ce qu'il faut éviter et pourquoi)
• Calibrage de la voix (comment l'auteur pense et communique)

Préserver 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.

Superposer 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. Aiguillez en fonction de ce que demande l'utilisateur :

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

Déclencheur : L'utilisateur fournit un ou plusieurs chemins de document/dossier/glob sans instructions spéciales Action : Exécuter toutes les étapes ci-dessous (Étapes 0–9) Résultat : Compétence complète avec SKILL.md, chapitres/, glossaire, patrons, aide-mémoire

2. Analyser uniquement

Déclencheur : L'utilisateur dit "analyser", "juste extraire", ou "je veux vérifier avant de générer" Action : Exécuter les Étapes 0–3, puis produire un rapport d'extraction structuré (frameworks, principes, techniques trouvés). Arrêter — NE PAS générer les fichiers de compétence. Résultat : Rapport d'analyse pour examen par l'utilisateur

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

Déclencheur : L'utilisateur a des notes d'analyse existantes ou a précédemment exécuté le mode analyse uniquement Action : Sauter les Étapes 0–3, utiliser l'analyse fournie comme entrée, exécuter les Étapes 4–9 Résultat : Fichiers de compétence à partir de l'analyse fournie

4. Mise à jour / Fusion (Compétence existante)

Déclencheur : L'utilisateur fournit un ou plusieurs nouveaux chemins source et indique vouloir mettre à jour une compétence existante (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écuter 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). Puis passer à l'Étape 5 (identifier/détecter le chemin de la compétence existante) et exécuter le Workflow de mise à jour / Fusion pour fusionner le nouveau contenu dans les fichiers de compétence existants. Résultat : 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é depuis plusieurs systèmes de compétences. Lors de la recherche du script d'assistance de ce convertisseur ou de l'écriture de la compétence de livre générée, privilégiez ces emplacements dans l'ordre :

1. Compétences personnelles GitHub Copilot CLI : ~/.copilot/skills/
2. Compétences personnelles inter-agents (Copilot, Amp, Codex) : ~/.agents/skills/
3. Compétences personnelles Claude Code : ~/.claude/skills/
4. Compétences projet-local Copilot : .github/skills/
5. Compétences projet-local Claude : .claude/skills/
6. Compétences projet-local Amp / Copilot : .agents/skills/
7. Compétences globales Amp : ~/.config/agents/skills/
8. Compétences globales Amp héritées : ~/.config/amp/skills/
9. Compétences personnelles Hermes Agent : $HERMES_HOME/skills/ (par défaut ~/.hermes/skills/)
10. Compétences projet-local Hermes Agent : .hermes/skills/ ou .agents/skills/

Pour les compétences de livre générées, privilégiez la racine inter-agents utilisateur ~/.agents/skills/ — une seule copie physique sert chaque hôte pris en charge. Copilot CLI et Amp la découvrent nativement ; Claude Code a besoin d'un lien symbolique depuis ~/.claude/skills/<nom_compétence> (créé à l'Étape 10, voir l'Étape 5 pour les règles). Choisissez une racine propre à l'hôte ou au projet seulement si l'utilisateur le demande.

---

É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 motif glob. Utilisation : book-to-skill <chemin-vers-dossier-ou-glob-de-document>... [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, dossier ou 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 INPUT_PATHS.
• Si un chemin d'entrée est un dossier 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 / Fusion (Mode 4).

---

Étape 1 — Valider l'entrée

Vérifiez qu'il y a au moins un fichier, dossier ou motif glob pris en charge parmi les INPUT_PATHS. Pour les dossiers 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 d'extraire, demandez à l'utilisateur :

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

1. Technique — contient des blocs de code, tableaux, formules, diagrammes (par exemple, livres de programmation, articles académiques, guides d'architecture)
2. Principalement du texte — surtout de la prose, peu ou pas de tableaux/code (par exemple, gestion, productivité, non-fiction narrative)
3. 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 procéder :

"📐 Mode technique sélectionné — utilisation de Docling pour une extraction avec conscience de 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. Texte brut/Markdown/HTML sont généralement prêts en quelques secondes ; les PDF utilisent pdftotext quand il est disponible."

---

Étape 2 — Extraire le texte des documents source

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

SCRIPT_PATH=""
HERMES_HOME_RESOLVED="${HERMES_HOME:-$HOME/.hermes}"
PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
HERMES_PROJECT_TRUSTED=false
if [ -n "$PROJECT_ROOT" ] && [ "${HERMES_AGENT:-}" = true ] && \
  command -v hermes >/dev/null 2>&1 && \
  command -v python3 >/dev/null 2>&1 && \
  hermes config get skills.trusted_project_dirs --json 2>/dev/null | PROJECT_ROOT="$PROJECT_ROOT" python3 -c 'import json, os, pathlib, sys; root=pathlib.Path(os.environ["PROJECT_ROOT"]).resolve(); sys.exit(not any(pathlib.Path(p).expanduser().resolve() == root for p in json.load(sys.stdin)))' 2>/dev/null
then
  HERMES_PROJECT_TRUSTED=true
fi

CANDIDATES=(
  "$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"
  "$HERMES_HOME_RESOLVED/skills/book-to-skill/scripts/extract.py"
  "$HERMES_HOME_RESOLVED"/skills/*/book-to-skill/scripts/extract.py
)
if [ "${HERMES_AGENT:-}" != true ]; then
  CANDIDATES+=(
    ".github/skills/book-to-skill/scripts/extract.py"
    ".claude/skills/book-to-skill/scripts/extract.py"
    ".agents/skills/book-to-skill/scripts/extract.py"
  )
fi
CANDIDATES+=(
  "$HOME/.config/agents/skills/book-to-skill/scripts/extract.py"
  "$HOME/.config/amp/skills/book-to-skill/scripts/extract.py"
)
if [ "$HERMES_PROJECT_TRUSTED" = true ]; then
  CANDIDATES=(
    "$PROJECT_ROOT/.hermes/skills/book-to-skill/scripts/extract.py"
    "$PROJECT_ROOT/.hermes/skills"/*/book-to-skill/scripts/extract.py
    "$PROJECT_ROOT/.agents/skills/book-to-skill/scripts/extract.py"
    "$PROJECT_ROOT/.agents/skills"/*/book-to-skill/scripts/extract.py
    "${CANDIDATES[@]}"
  )
fi
for candidate in "${CANDIDATES[@]}"
do
  if [ -f "$candidate" ]; then
    SCRIPT_PATH="$candidate"
    break
  fi
done

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

PYTHON_BIN="${PYTHON_BIN:-python3}"
if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
  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 est manquant, il invite l'utilisateur avec la solution de repli disponible. Les sessions non interactives utilisent par défaut la solution de repli, sauf si le mode d'installation est explicitement yes.

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

Ceci crée un répertoire de travail par exécution — <tempdir>/book_skill_work-<pid>/ par défaut, ou exactement le chemin que vous avez défini dans BOOK_SKILL_WORKDIR — contenant :

• full_text.txt — texte extrait combiné de toutes les sources avec des limites visuellement nettement démarquées.
• metadata.json — taille totale combinée, mots, pages, comptes de tokens, comptes d'images EPUB supprimées, le workdir résolu, et une liste détaillée des sources individuelles traitées.

L'exécution imprime les trois chemins à la fin (Workdir ->, Text ->, Meta ->). Prenez les chemins à partir de cette sortie (ou du champ workdir propre à metadata.json) plutôt que de supposer un emplacement fixe — le nom du répertoire diffère à chaque exécution afin que des extractions simultanées sur une même machine ne puissent pas écraser les résultats les unes des autres.

Lisez le metadata.json de cette exécution pour inspecter les résultats.

Confirmez toujours que l'extraction correspond au document demandé avant de générer quoi que ce soit : vérifiez filename / source_file dans metadata.json, ou l'en-tête SOURCE: sur la première ligne de full_text.txt. Si vous attendez une exécution en arrière-plan, attendez sur son workdir spécifique — interroger un chemin partagé pourrait afficher la sortie d'une autre exécution.

---

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

Lisez le metadata.json de cette exécution (le chemin Meta -> de la sortie d'extraction) et présentez à l'utilisateur une estimation avant toute génération :

📖 Sources détectées : <total_sources> source(s)
<liste chaque nom de fichier source et format depuis la liste des sources des métadonnées>
<si images_dropped > 5 : avertir que N images source n'ont pas été lues>
📄 Pages/Sections combinées : ~<N> | Mots : ~<N> | Tokens totaux : ~<N>K

💰 Estimation du coût 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 comptes de tokens ci-dessus par les taux
   d'entrée/sortie par million de tokens actuels de votre modèle
   (les prix et les noms de modèles changent souvent —
   ne les codez pas en dur ; citez le taux d'aujourd'hui et
   étiquetez-le comme une estimation).

   ⏱  Temps estimé : ~<N> minutes

📁 Fichiers à générer/mettre à jour :
   SKILL.md + fichiers de chapitre + glossaire + patrons + aide-mémoire

➡  Procéder à la Conversion complète / Mise à jour ? (ou tapez "analyser 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 + patrons + aide-mémoire)
  • Budget par chapitre médian 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 comptes de tokens et multipliez par les taux d'entrée/sortie actuels par million de tokens de l'utilisateur. Ne codez PAS les montants en dollars en dur — les noms de modèles et les prix changent ; si vous en affichez un, étiquetez-le comme une estimation et datez-le.

Attendez la confirmation de l'utilisateur avant de continuer. S'il dit "analyser uniquement", passez au Mode 2.

---

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

Inspiré du paradigme du modèle de langage récursif (RLM) : traitez full_text.txt comme un corpus interrogeable, pas comme une seule lecture. Charger tout le fichier dans le contexte épuise le budget dont vous aurez besoin plus tard pour la génération.

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

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

# Trouver les décalages de chapitre sans charger tout le fichier
grep -n -E "^\s*(Chapter|CHAPTER)\s+[0-9]+" "$FULL_TEXT_PATH" | head -40

# Extraire uniquement le chapitre dont vous avez besoin (lignes de début..fin incluses)
sed -n '<debut>,<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 tout le fichier
# Read(chemin_fichier=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 du glossaire / des patrons). Pour les livres de moins de 50 000 tokens, une seule Read suffit.

Pourquoi c'est important : un livre de 200 pages fait ~75 000 tokens. Le relire une fois par chapitre (28 passages) c...