cangjie-skill — 把一本书蒸馏成一组可执行 skills 的元 skill

Sources / Amont

• Amont : https://github.com/kangarooking/cangjie-skill
• Licence : MIT
• Vendu dans : .agents/skills/book-to-skill-distill/SKILL.md pour l'installation partagée Moi/Codex
• Remarque : Le pipeline complet nécessite également methodology/ et extractors/ du dépôt amont.

Ce fichier peut être une copie vendue ou un pointeur fin. Préférez installer/cloner le dépôt amont lorsqu'il contient des ressources, des scripts ou des obligations AGPL.

cangjie-skill — Distiller un livre en un ensemble de skills exécutables

Mission

Décomposer la méthodologie d'un livre en capacités atomiques, invocables par un agent dans des situations réelles, et les compiler en un nombre approprié de skills selon l'objectif de l'utilisateur, pour que le lecteur puisse réellement les utiliser.

Convention terminologique : Dans ce document, ainsi que dans methodology/ et extractors/, le terme « livre » désigne tout contenu long à distiller : livres, transcriptions de vidéos longues, retranscriptions de podcasts, cours, entretiens, articles longs, collections de données.

Limites :

• ✅ Fait : Distillation de méthodologies / cadres de décision / procédures / règles de calcul / dépannage / listes de contrôle / principes, avec le système de concepts comme support de référence.
• ❌ Ne fait pas : Résumé de livre / compte-rendu de lecture / jeu de rôle en tant qu'auteur (pour cela, utilisez nuwa-skill).

Méthodologie centrale : RIA-TV++ (version Bundle v2.5)

Un pipeline en cinq phases + extraction parallèle + triple vérification + porte de promotion + test de compatibilité darwin. Voir methodology/00-overview.md pour les détails.

Phase 0 :  Compréhension globale Adler       → BOOK_OVERVIEW.md
Phase 1 :  5 agents d'extraction parallèle    → Pool d'unités candidates
Phase 1.5 : Filtrage par triple vérification   → Unités passées (validation légère par l'utilisateur)
Phase 1.6 : Porte de promotion Skill (indépendance) → promu / routeur
Phase 2 :  Construction de fiches RIA++       → .cangjie/capabilities/cards/<slug>.md
Phase 3 :  Liaison Zettelkasten               → also_read + GLOSSARY dans verified.yaml
Phase 4 :  Test de résistance (darwin-compat) → Cas d'évaluation + retour en arrière
Phase 5 :  Compilation et livraison           → cangjie.py compile (single/pack) + DIGEST.md + installation

Changement clé v2.5 (ADR-002) : Les phases 2 à 4 n'écrivent plus directement des répertoires de skill finaux pour chaque unité. À la place, elles produisent un Capability Bundle (books/<slug>/.cangjie/capabilities/verified.yaml + cards/*.md). Les modes single et pack sont tous deux compilés de manière déterministe à partir de ce même Bundle par scripts/cangjie.py compile, en utilisant un ensemble stable de capability_id. L'ancienne sortie one-to-one est toujours prise en charge (legacy-pack, voir docs/migrations/2026-08-25-v2.0-to-v2.1.md).

Quand appeler ce skill

L'utilisateur dit quelque chose comme :

• "Aide-moi à décomposer « Poor Charlie's Almanack »"
• "Transforme « Le Petit Livre Rouge » en skill"
• "Distille cette vidéo Bilibili / ce podcast / ce cours en skill"
• "distill this book into skills: "
• "Je veux rendre la méthodologie de ce livre utilisable comme skill"

Configuration d'entrée

Avant de commencer, vous devez confirmer avec l'utilisateur :

Dépendance de script : Les scripts déterministes (scripts/) nécessitent Python 3.10+ et PyYAML (python3 -m pip install pyyaml). Si PyYAML est manquant, exécutez d'abord python3 scripts/cangjie.py doctor pour une auto-vérification, qui donnera les instructions d'installation.

1. Source du texte du contenu : Chemin du PDF / EPUB / TXT / fichier de sous-titres / transcription, ou texte brut accessible. Ne pas distiller "de mémoire" sans texte — arrêtez-vous et demandez à l'utilisateur. (Pour les vidéos/podcasts, utilisez d'abord un outil comme un téléchargeur de vidéo pour obtenir la transcription.)
2. Méta-informations du contenu : Pour un livre : "titre + auteur + année de publication" ; pour une vidéo/podcast/cours : "titre + auteur (créateur/intervenant) + date de publication". Utilisé pour la dénomination des répertoires et l'audit.
3. Objectif d'utilisation (détermine le mode de sortie recommandé) : Apprendre/consulter ce livre → tendance single ; intégration dans un flux de travail quotidien, combinaison avec d'autres livres → tendance pack. En cas d'incertitude, recommandez d'abord single (principe du single-first).
4. Premier essai ? : Si l'utilisateur utilise ce skill pour la première fois, recommandez de distiller 1 contenu pour valider le processus avant de passer en mode batch.

Mapping des champs pour les contenus non-livres : Les champs de type chapitre sont mappés à des horodatages ou des parties pour les vidéos, aux numéros d'épisode pour les podcasts, et aux numéros de leçon pour les cours — tant que c'est traçable.

Structure de sortie

books/<book-slug>/
├── PIPELINE_STATE.md          # État du pipeline : phase en cours + progression (pour reprise)
├── BOOK_OVERVIEW.md           # Sortie de la phase 0 : objectif / squelette / terminologie / critique
├── verified.md                # Sortie de la phase 1.5 : unités passant la triple vérification + justifications
├── coverage-audit.md          # Tâches clés du livre → candidates → verdict → destination de livraison
├── references.md              # Contenu de référence sans exécution + leur cartographie de livraison
├── needs-review.md            # Sources / conditions / lacunes de test ; non compilé en capacités actives
├── GLOSSARY.md                # Sortie de la phase 3 : dictionnaire de termes partagé
├── DIGEST.md                  # Sortie de la phase 5 : article de fond pour le lecteur
├── candidates/                # Sortie de la phase 1 : pool de candidats bruts (pour audit)
├── rejected/                  # Unités éliminées à la phase 1.5 + raisons (pour audit)
└── .cangjie/                  # Couche v2.5 (source de vérité de compilation + journal d'exécution)
    ├── capabilities/
    │   ├── verified.yaml      # Capability Bundle (source de vérité unique pour la compilation, schema capability-bundle.schema.json)
    │   ├── cards/<slug>.md    # Fiches de capacité RIA (R/I/A1/A2/E/B, sortie phase 2)
    │   ├── resources/         # Scripts UTF-8, modèles CSV/JSON/Markdown déclarés explicitement (optionnel)
    │   ├── destinations.json  # Mappage des destinations de promotion/routage (sortie phase 1.6)
    │   └── book/{overview.md,glossary.md}
    ├── runs/<run-id>/         # Rapports de décision et journaux de validation pour chaque compilation/mise à jour
    └── snapshots/             # Instantanés avant publication (pour rollback)

La livraison finale est compilée à partir du Bundle par scripts/cangjie.py compile (--output single donne 1 point d'entrée + fiches de capacité ; --output pack donne 1 point d'entrée de routage de source + quelques skills promus).

Processus d'exécution (strictement dans l'ordre)

Reprise sur interruption : Avant de commencer, vérifiez si books/<slug>/PIPELINE_STATE.md existe. S'il existe, lisez-le et reprenez à partir de la phase enregistrée. Ne recommencez pas depuis le début. Mettez à jour ce fichier après chaque phase.

Phase 0 — Compréhension globale du livre

1. Lisez le texte du livre fourni par l'utilisateur. Découpez les gros fichiers en blocs.
2. Exécutez les quatre étapes Adler (structure / interprétation / critique / application) de methodology/01-stage0-adler.md.
3. Remplissez le modèle selon templates/BOOK_OVERVIEW.md.template, écrivez dans books/<slug>/BOOK_OVERVIEW.md.
4. Présentez la sortie à l'utilisateur pour confirmation : "Ai-je bien compris la structure? Y a-t-il des axes que tu aimerais voir mis en avant ?" Attendez la confirmation avant de passer à la phase 1.

Phase 1 — Extraction parallèle par 5 sous-agents

En parallèle, créez 5 sous-agents de tâche (en utilisant l'outil Agent, en lançant les 5 dans un seul appel) :

sous-agent	prompt lu	stratégie de contexte	sortie
Extracteur de cadres	extractors/framework-extractor.md	Analyse complète (transversale et mécanismes complets)	Cadres de décision / modèles de pensée / processus / dépannage
Extracteur de principes	extractors/principle-extractor.md	Analyse complète (formules, tableaux, notes de bas de page)	Principes / listes de contrôle / règles / règles de calcul
Extracteur de cas	extractors/case-extractor.md	Extraction par bloc (ciblé)	Exemples du livre, cas reformulés, exercices, avec type
Extracteur de contre-exemples	extractors/counter-example-extractor.md	Extraction par bloc (ciblé)	Modes d'échec signalés dans le livre
Extracteur de glossaire	extractors/glossary-extractor.md	Extraction par bloc + pré-filtrage par script	Dictionnaire de concepts clés

Chaque sous-agent juge et produit indépendamment dans books/<slug>/candidates/<type>.md.

• Texte long : Pour le contenu dépassant le contexte d'un sous-agent, suivez la stratégie de découpage de methodology/02-stage1-parallel-extract.md ; si un index de contenu (.cangjie/index/) existe, les extracteurs par bloc prennent les blocs pertinents par index.
• Porte de couverture dure : Croisez simultanément les candidats de l'analyse complète et la liste des tâches clés de la phase 0. Ne vérifiez pas seulement les anciens éléments passés. Les tâches importantes doivent avoir un candidat et une destination claire ; en cas d'écart inexpliqué, relisez/revenez à l'analyse complète, ne déclarez pas zéro écart.
• Plan de repli : Si l'environnement ne supporte pas les sous-agents parallèles, exécutez les 5 extracteurs en série en utilisant les mêmes prompts, le format de sortie reste inchangé.

Phase 1.5 — Filtrage par triple vérification (validation des connaissances)

Lisez methodology/03-stage1.5-triple-verify.md. Pour chaque unité candidate, exécutez :

• V1 Suffisance de la source : Le texte source est-il suffisant pour étayer la pratique dans la portée définie ? Un mécanisme complet expliqué en un seul endroit est également acceptable.
• V2 Exécutabilité : Une nouvelle entrée valide permet-elle d'accomplir la tâche et de vérifier le résultat ? Pas de généralisation inter-domaines obligatoire.
• V3 Gain de tâche : Permet-il de réduire les oublis, d'uniformiser les critères ou de stabiliser la livraison ? Pas d'exigence d'originalité de l'auteur.

Divisez en verified / reference / needs_review / rejected, enregistrez les justifications et les lacunes ; le contenu de référence doit être cartographié vers l'overview/glossary réellement livré. Tous les éléments non passés ne sont pas éliminés. Mettez à jour coverage-audit.md.

Validation légère par l'utilisateur ★ : Présentez les quatre catégories (exécutable, référence, à vérifier, éliminé) et les lacunes importantes, puis passez à la phase 1.6. La validation ne remplace pas la vérification de la source.

Phase 1.6 — Porte de promotion Skill indépendant (validation produit)

Lisez methodology/03b-stage1.6-promotion-gate.md. Une unité vérifiée n'est pas nécessairement un bon skill indépendant. Pour chaque unité, évaluez les cinq critères (intention indépendante / contrat indépendant / exécution indépendante / réutilisation indépendante / évaluation indépendante — les 3 premiers obligatoires, au moins 1 sur les 2 derniers), écrivez la destination dans promotion.destination du Bundle (promoted / router). Les unités non promues ne sont pas éliminées ; elles restent comme fiches de capacité dans le point d'entrée de routage de source. Le budget doux du point d'entrée de routage est par défaut de 8 (incluant 1 point d'entrée de routage de source).

Phase 2 — Construction de fiches RIA++

Pour chaque unité passée, construisez une fiche de capacité en six sections (R / I / A1 / A2 / E / B) selon methodology/04-stage2-ria-plus.md :

• Le corps de la fiche est écrit dans books/<slug>/.cangjie/capabilities/cards/<slug>.md (sans frontmatter ; les données frontmatter sont enregistrées dans le Bundle) ;
• En même temps, enregistrez la capacité dans verified.yaml : capability_id stable, intents, keywords, one_liner, importance (avec justification), frontmatter.description (version condensée d'A2).
• A1 distingue les cas originaux du livre des exercices synthétiques clairement marqués ; E précise les entrées, sorties, branches et critères d'achèvement. Si nécessaire, déclarez explicitement les ressources textuelles d'accompagnement via resources, voir la description de la phase 2.

Phase 3 — Liaison Zettelkasten

Selon methodology/05-stage3-zettelkasten.md :

1. Identifiez les relations de citation entre les capacités, écrivez also_read dans le Bundle pour chaque capacité, et remplissez la section A2 "différence avec les capacités voisines".
2. Organisez candidates/glossary.md en books/<slug>/GLOSSARY.md, et copiez-le dans .cangjie/capabilities/book/glossary.md.
3. L'INDEX/table de routage est généré par le compilateur à partir du Bundle, plus de rédaction manuelle.
4. Fusionnez le contenu à conserver de references.md dans book/overview.md ou book/glossary.md du Bundle, en enregistrant le chemin réel dans l'audit de couverture ; ne déguisez pas le contenu à vérifier en méthode exécutable.

Phase 4 — Test de résistance (darwin-compat)

Selon methodology/06-stage4-pressure-test.md : les capacités promues sont testées sur leur déclenchement ; les capacités de routage sont testées sur leur accessibilité. Les deux types doivent effectivement accomplir une tâche représentative et vérifier la sortie. Ne pas utiliser "ça sera appelé" à la place de "ça fait correctement". Les sorties manquantes sont comptées dans le dénominateur de l'évaluation ; ne déclarez pas de passage si ce n'est pas terminé. Les capacités non passées retournent à la phase 2.

Phase 5 — Compilation et livraison

Selon methodology/07-stage5-deliver.md :

1. Générez books/<slug>/DIGEST.md — un article de fond pour le lecteur.
2. Exécutez python3 scripts/cangjie.py compile --bundle books/<slug>/.cangjie/capabilities --out <répertoire_cible> --output auto, présentez le rapport de décision à l'utilisateur pour validation légère (selon la recommandation / passer en single / passer en pack).
3. Demandez à l'utilisateur l'emplacement d'installation, copiez ou créez un lien symbolique des artefacts compilés.
4. Informez l'utilisateur : "Terminé. Vous pouvez maintenant le donner à darwin-skill pour une évolution automatique."

Lignes rouges qualité (violation = bloquer la sortie)

1. Chaque capacité doit passer toutes les trois vérifications.
2. Chaque fiche de capacité doit avoir les six sections R / I / A1 / A2 / E / B complètes ; si A1 n'a pas de cas original du livre, marquez-le explicitement ; les exercices synthétiques ne peuvent pas usurper les faits du livre.
3. Citations originales ≤150 caractères/paragraphe (≤100 mots/paragraphe en anglais).
4. Chaque capacité active a exactement une destination dans destinations.json (promoted_to ou served_by) ; les capacités non promues doivent être accessibles via le point d'entrée de routage de source.
5. La description du skill promu doit clairement spécifier les conditions de déclenchement et avoir des contre-exemples proches avec le point d'entrée de source.
6. Les artefacts compilés doivent passer scripts/validate_skill_pack.py (format / références relatives / frontmatter à 100%).
7. Le répertoire généré est en lecture seule : ne pas écraser silencieusement en cas de modifications locales manuelles (le compilateur impose un choix parmi trois options).
8. La couverture des tâches clés doit avoir une destination traçable ; l'évaluation de la sortie réelle et la vérification de la source sont enregistrées séparément. En cas de lacune importante, ne livrez qu'un brouillon avec un périmètre clairement marqué, ne déclarez pas un passage complet.

Positionnement dans l'écosystème nuwa-skill / darwin-skill

• nuwa-skill : Distille les personnes (modes de pensée / expression ADN).
• cangjie-skill (ce skill) : Distille les livres (méthodologies / cadres / principes).
• darwin-skill : Fait évoluer n'importe quel skill.

Les trois s'emboîtent : Les cas d'évaluation produits par ce skill suivent le format de darwin-skill, afin que les skills produits puissent être directement intégrés à darwin pour une évolution automatique.

Conventions d'appel

• Toujours tester 1 livre en premier — sauf si l'utilisateur dit explicitement "en batch".
• Signaler la progression entre les phases — ne pas exécuter en silence puis déverser les résultats.
• Ne pas distiller de mémoire — sans texte, arrêtez-vous et demandez.
• Conserver la piste d'audit — les répertoires candidates/ et rejected/ doivent être conservés.
• Reprise possible à tout moment — mettez à jour PIPELINE_STATE.md après chaque phase ; en cas d'interruption, reprenez à partir du fichier d'état.
• Persistance de la stratégie de sortie — update/repair utilise par défaut le mode de sortie d'origine ; ne changez pas silencieusement la forme des artefacts en raison de nouveaux matériaux.