Quellen / Upstream

Upstream: https://github.com/kangarooking/cangjie-skill
Lizenz: MIT
Vendored in: .agents/skills/book-to-skill-distill/SKILL.md für Moi/Codex shared install
Hinweis: Für die vollständige Pipeline werden auch die Methodiken und Extrakteure aus dem Upstream-Repository benötigt.

Diese Datei kann eine vendierte Kopie oder ein dünner Verweis sein. Bevorzuge die Installation/das Klonen des Upstream-Repos, wenn es Assets, Skripte oder AGPL-Verpflichtungen mit sich bringt.

cangjie-skill – Meta-Skill zum Destillieren eines Buchs in einen Satz ausführbarer Skills

Mission

Die in einem Buch enthaltenen Methodiken zerlegen in atomare, von einem Agenten in realen Szenarien aufrufbare Fähigkeiten und diese entsprechend dem Benutzerzweck in eine angemessene Anzahl von Skills kompilieren, damit der Leser sie wirklich nutzen kann.

Begriffsvereinbarung: Dieses Dokument sowie methodology/ und extractors/ verwenden den Begriff „Buch“ für alle langen Inhalte, die destilliert werden – Bücher, lange Videotranskripte, Podcast-Transkripte, Kurse, Interviews, lange Artikel, Materialsammlungen.

Abgrenzung:

✅ Umfasst: Destillation von Methodiken, Entscheidungsrahmen, Arbeitsabläufen, Berechnungsregeln, Fehlerbehebungen, Checklisten, Prinzipien; Konzeptsysteme als unterstützende Referenz
❌ Ausgeschlossen: Buchzusammenfassungen, Rezensionen, Rollenspiele als Autor (dafür bitte nuwa-skill verwenden)

Kernmethodik: RIA-TV++ (v2.5 Bundle Edition)

Eine Pipeline mit fünf Phasen, paralleler Extraktion, dreifacher Validierung, Promotion-Gate und Darwin-Kompatibilitätstests. Details siehe methodology/00-overview.md.

Phase 0:   Adler-Ganzbuchverständnis        → BOOK_OVERVIEW.md
Phase 1:   5 parallele Agent-Extraktionen    → Kandidatenpool für Methodik-Einheiten
Phase 1.5: Dreifach-Validierung (Wissensprüfung) → bestandene Einheiten (leichte Benutzerbestätigung)
Phase 1.6: Promotion-Gate für eigenständige Skills (Produktreifeprüfung) → promoted / router Bestimmung
Phase 2:   RIA++-Fähigkeitskarten-Konstruktion → .cangjie/capabilities/cards/<slug>.md
Phase 3:   Zettelkasten-Verknüpfung            → also_read in verified.yaml + GLOSSARY
Phase 4:   Stresstest (Darwin-Kompatibilität)  → Testfälle + erneute Verarbeitung bei Fehlern
Phase 5:   Kompilierung und Auslieferung       → cangjie.py compile (single/pack) + DIGEST.md + Installation

Wichtige Änderung in v2.5 (ADR-002): Die Phasen 2–4 schreiben keine einzelnen, endgültigen Skill-Verzeichnisse mehr direkt. Stattdessen wird ein Fähigkeitsbündel erstellt (books/<slug>/.cangjie/capabilities/verified.yaml + cards/*.md). Sowohl single als auch pack werden aus demselben Bündel durch scripts/cangjie.py compile deterministisch kompiliert; beide referenzieren denselben Satz stabiler capability_ids. Die alte One-to-One-Ausgabe wird weiterhin unterstützt (Legacy-Pack, siehe docs/migrations/2026-08-25-v2.0-to-v2.1.md).

Wann dieser Skill aufgerufen werden sollte

Der Benutzer sagt etwa:

„Hilf mir, ‚Poor Charlie‘s Almanack‘ zu zerlegen“
„Destilliere die Werke von Mao zu einem Skill“
„Destilliere dieses Bilibili-Video/diesen Podcast/diesen Kurs zu einem Skill“
„distill this book into skills: “
„Ich möchte die Methodiken aus diesem Buch in einen nutzbaren Skill verwandeln“

Eingabeanforderungen

Vor Beginn muss Folgendes vom Benutzer bestätigt werden:

Skript-Abhängigkeiten: Die deterministischen Skripte (scripts/) benötigen Python 3.10+ und PyYAML (python3 -m pip install pyyaml). Fehlt PyYAML, führe zuerst python3 scripts/cangjie.py doctor zur Selbstprüfung aus. Es gibt Installationsanleitungen.

Quelle des Inhaltstextes: Pfad zu PDF/EPUB/TXT/Untertiteldatei/Transkript, oder zugänglicher Klartext. Destilliere nicht aus dem Gedächtnis, wenn kein Text vorliegt – halte lieber inne und frage den Benutzer. (Für Videos/Podcasts wird empfohlen, zuerst mit einem Video-Downloader-Tool das Transkript zu besorgen.)
Metadaten des Inhalts: Bei Büchern „Titel + Autor + Erscheinungsjahr“; bei Videos/Podcasts/Kursen „Titel + Autor (UP-Moderator/Sprecher/Dozent) + Veröffentlichungszeitpunkt“. Dient der Verzeichnisbenennung und Prüfprotokollierung.
Verwendungszweck (bestimmt die empfohlene Ausgabeform): Lernen/Nachschlagen des Buches → Tendenz zu single; Integration in den täglichen Arbeitsablauf, kombinieren mit anderen Büchern → Tendenz zu pack. Bei Unsicherheit nach dem Single-First-Prinzip zuerst single empfehlen.
Handelt es sich um einen ersten Pilotversuch?: Wenn der Benutzer cangjie-skill zum ersten Mal verwendet, wird empfohlen, zuerst einen Inhalt zu destillieren, um den Ablauf zu validieren, bevor eine Batch-Verarbeitung durchgeführt wird.

Feldzuordnung für Nicht-Buch-Inhalte: Inhaltsangaben-Felder: Bei Videos Zeitstempel oder Kapitelnummern, bei Podcasts Episodennummern, bei Kursen Lektionsnummern – sofern die Nachvollziehbarkeit gewährleistet ist.

Ausgabestruktur

buecher/<buch-slug>/
├── PIPELINE_STATE.md          # Pipeline-Status: aktuelle Phase + Fortschritt (für Wiederaufnahme)
├── BOOK_OVERVIEW.md           # Ausgabe Phase 0: Kernthese/Gerüst/Fachbegriffe/Kritik
├── verified.md                # Ausgabe Phase 1.5: Bestandene Einheiten mit Begründung
├── coverage-audit.md          # Schlüsselaufgaben des Originalbuchs → Kandidaten → Entscheidung → tatsächliche Lieferziele
├── references.md              # Belegte, aber nicht ausgeführte Referenzinhalte mit Lieferzuordnung
├── needs-review.md            # Quellen-/Bedingungs-/Testlücken; nicht zu aktiven Fähigkeiten kompiliert
├── GLOSSARY.md                # Ausgabe Phase 3: Gemeinsames Glossar des gesamten Buches
├── DIGEST.md                  # Ausgabe Phase 5: Zusammenfassender langer Text für den Leser
├── candidates/                # Ausgabe Phase 1: Rohkandidatenpool (für Prüfzwecke)
├── rejected/                  # Phase 1.5: Ausgeschlossene Einheiten mit Gründen (für Prüfzwecke)
└── .cangjie/                  # v2.5 Sidecar-Schicht (kompilierte Faktenquelle + Ausführungsprotokoll)
    ├── capabilities/
    │   ├── verified.yaml      # Fähigkeitsbündel (einzige Faktenquelle für Kompilierung, gemäß capability-bundle.schema.json)
    │   ├── cards/<slug>.md    # RIA-Fähigkeitskarte (R/I/A1/A2/E/B, Ausgabe Phase 2)
    │   ├── resources/         # Explizit deklarierte UTF-8-Skripte, CSV/JSON/Markdown-Vorlagen (optional)
    │   ├── destinations.json  # Promotion/Routing-Zuordnung (Ausgabe Phase 1.6)
    │   └── book/{overview.md,glossary.md}
    ├── runs/<run-id>/         # Entscheidungsberichte und Validierungsprotokolle jeder Kompilierung/Aktualisierung
    └── snapshots/             # Snapshots vor der Veröffentlichung (für Rollback)

Das endgültige Lieferobjekt wird durch scripts/cangjie.py compile aus dem Bündel kompiliert (--output single ergibt 1 Einstiegspunkt + Fähigkeitskarten; --output pack ergibt 1 Quellen-Routing-Einstiegspunkt + einige wenige promotete Skills).

Ausführungsablauf (strikt sequentiell)

Wiederaufnahme: Prüfe vor Beginn, ob books/<slug>/PIPELINE_STATE.md existiert. Wenn ja, lies den Stand und setze die Verarbeitung ab der protokollierten Phase fort; beginne nicht von vorne. Aktualisiere die Datei nach Abschluss jeder Phase.

Phase 0 – Ganzbuchverständnis

Lies den vom Benutzer bereitgestellten Buchtext. Große Dateien in Blöcken lesen.
Führe die Adler-Vier-Schritte (Struktur/Interpretation/Kritik/Anwendung) aus methodology/01-stage0-adler.md durch.
Befülle die Vorlage aus templates/BOOK_OVERVIEW.md.template und schreibe sie in books/<slug>/BOOK_OVERVIEW.md.
Zeige die Ausgabe dem Benutzer zur Bestätigung: „Habe ich das Gerüst richtig verstanden? Gibt es einen Schwerpunkt, den du besonders betonen möchtest? Hole dir die Bestätigung, bevor du mit Phase 1 fortfährst.

Phase 1 – Parallele Extraktion durch 5 Sub-Agenten

Starte parallel 5 Task-Sub-Agenten (verwende das Agent-Tool, starte alle 5 in einem Aufruf):

Sub-Agent	Gelesene Anweisung	Kontextstrategie	Ausgabe
Framework-Extraktor	`extractors/framework-extractor.md`	Vollständiger Scan (sowohl kapitelübergreifend als auch Einzelstellen mit vollständigem Mechanismus)	Entscheidungsrahmen/Denkmodelle/Prozesse/Fehlerbehebung
Prinzipien-Extraktor	`extractors/principle-extractor.md`	Vollständiger Scan (inkl. Formeln, Tabellen, Fußnoten)	Prinzipien/Checklisten/Regeln/Berechnungskennzahlen
Fall-Extraktor	`extractors/case-extractor.md`	Retrieval-basiert (lokale Treffer)	Beispiele aus dem Buch, paraphrasierte Fälle, Übungsaufgaben, mit Typenangabe
Gegenbeispiel-Extraktor	`extractors/counter-example-extractor.md`	Retrieval-basiert (lokale Treffer)	Im Buch gewarnte Fehlermuster
Begriff-Extraktor	`extractors/glossary-extractor.md`	Retrieval-basiert + Skript-Vorabfilter	Schlüsselkonzept-Glossar

Jeder Sub-Agent entscheidet unabhängig und schreibt seine Ausgabe in books/<slug>/candidates/<type>.md.

Lange Texte: Inhalte, die den Kontext eines einzelnen Sub-Agenten überschreiten, werden gemäß der Chunking-Strategie aus methodology/02-stage1-parallel-extract.md verarbeitet. Wenn bereits ein Inhaltsverzeichnis (.cangjie/index/) vorhanden ist, rufen retrieval-basierte Extraktoren die relevanten Blöcke über den Index ab.
Coverage-Härtefall: Vergleiche gleichzeitig die Kandidaten aus dem vollständigen Scan mit der Schlüsselaufgabenliste aus Phase 0 des Originalbuchs. Prüfe nicht nur die bestandenen Elemente der alten Version. Wichtige Aufgaben müssen einen Kandidaten und ein klares Ziel haben; bei ungeklärten Lücken nachlesen/zum vollständigen Scan zurückkehren, keine falschen Null-Lücken melden.
Downgrade-Strategie: Wenn die Umgebung keine parallelen Sub-Agenten unterstützt, werden die 5 Extraktor-Anweisungen seriell ausgeführt, das Ausgabeformat bleibt gleich.

Phase 1.5 – Dreifache Validierung (Wissensprüfung)

Lies methodology/03-stage1.5-triple-verify.md und führe für jede Kandidaten-Einheit folgende Prüfungen durch:

V1 Quellenhinlänglichkeit: Ist der Originaltext ausreichend, um die beschriebene Vorgehensweise innerhalb des definierten Rahmens zu stützen? Ein vollständiger Mechanismus an einer Stelle reicht aus.
V2 Ausführbarkeit: Kann mit legitimen neuen Eingaben die Aufgabe erfüllt und das Ergebnis verifiziert werden? Keine domänenübergreifende Extrapolation erforderlich.
V3 Aufgabenmehrwert: Reduziert die Einheit das Risiko von Auslassungen, sorgt für einheitliche Maßstäbe oder stabilisiert die Lieferung? Keine Originalität des Autors erforderlich.

Teile die Einheiten in verified / reference / needs_review / rejected ein, dokumentiere die Belege und Lücken; Referenzinhalte müssen tatsächlich in den Auslieferungen (overview/glossary) abgebildet werden; nicht alle nicht bestandenen Elemente werden ausgeschlossen. Aktualisiere coverage-audit.md.

Leichte Benutzerbestätigung ★: Zeige die vier Kategorien (ausführbare Kandidaten, Referenzen, zu prüfende, ausgeschlossene) und wichtige Lücken, bevor du mit Phase 1.6 fortfährst. Die Bestätigung ersetzt nicht die Quellenvalidierung.

Phase 1.6 – Promotion-Gate für eigenständige Skills (Produktreifeprüfung)

Lies methodology/03b-stage1.6-promotion-gate.md. Das Bestehen der Wissensvalidierung bedeutet nicht, dass jede Einheit ein eigenständiger Skill werden sollte. Prüfe jede Einheit anhand von fünf Kriterien (eigenständige Intention/eigenständiger Vertrag/eigenständige Ausführung/eigenständige Wiederverwendung/eigenständige Bewertung; die ersten 3 müssen bestanden sein, von den letzten 2 mindestens 1) und trage das Ziel in das promotion.destination-Feld des Bündels ein (promoted / router). Nicht promotete Einheiten werden nicht verworfen, sondern bleiben als Fähigkeitskarten im Quellen-Routing-Einstiegspunkt erhalten. Das weiche Budget für Einstiegspunkte beträgt standardmäßig 8 (einschließlich 1 Quellen-Routing-Einstiegspunkt).

Phase 2 – RIA++-Fähigkeitskarten-Konstruktion

Erstelle für jede bestandene Einheit gemäß methodology/04-stage2-ria-plus.md eine R-/I-/A1-/A2-/E-/B-Sechsteil-Fähigkeitskarte:

Schreibe den Karteninhalt in books/<slug>/.cangjie/capabilities/cards/<slug>.md (ohne Frontmatter, Frontmatter-Daten werden im Bundle gespeichert);
Registriere die Fähigkeit gleichzeitig in verified.yaml: stabile capability_id, Intents, Keywords, one_liner, importance (mit Begründung), frontmatter.description (A2-kondensierte Version).
A1 unterscheidet zwischen Originalbuch-Beispielen und explizit gekennzeichneten synthetischen Übungen; E spezifiziert Eingabe, Ausgabe, Verzweigungen und Erfolgskriterien. Deklariere bei Bedarf über resources explizit zugehörige Textressourcen (siehe Erläuterungen in Phase 2).

Phase 3 – Zettelkasten-Verknüpfung

Gemäß methodology/05-stage3-zettelkasten.md:

Identifiziere Referenzbeziehungen zwischen den Fähigkeiten und trage sie in das also_read-Feld der jeweiligen Fähigkeiten im Bundle ein. Ergänze die A2-Differenzierung zu benachbarten Fähigkeiten.
Sortiere das candidates/glossary.md zu books/<slug>/GLOSSARY.md und kopiere es in .cangjie/capabilities/book/glossary.md.
Das INDEX/Routing wird vom Compiler aus dem Bundle generiert; kein manuelles Schreiben.
Integriere die aus references.md zu erhaltenden Inhalte in das book/overview.md oder book/glossary.md des Bündels und protokolliere den tatsächlichen Pfad im Coverage-Audit. Vermeide es, zu prüfende Inhalte als ausführbare Methoden zu tarnen.

Phase 4 – Stresstest (Darwin-Kompatibilität)

Gemäß methodology/06-stage4-pressure-test.md: Get promotete Fähigkeiten auf Auslösbarkeit testen, Router-Fähigkeiten auf Erreichbarkeit; beide Typen müssen tatsächlich repräsentative Aufgaben abschließen und die Ausgabe überprüfen – „wird aufgerufen“ ersetzt nicht „macht es richtig“. Fehlende Ausgaben werden in den Evaluierungs-Nenner aufgenommen; nicht abgeschlossene Fähigkeiten werden nicht als bestanden deklariert. Nicht bestandene Fähigkeiten gehen zurück zu Phase 2.

Phase 5 – Kompilierung und Auslieferung

Gemäß methodology/07-stage5-deliver.md:

Generiere books/<slug>/DIGEST.md – einen zusammenfassenden Langtext für den Leser.
Führe python3 scripts/cangjie.py compile --bundle buecher/<slug>/.cangjie/capabilities --out <Zielverzeichnis> --output auto aus. Zeige den Entscheidungsbericht dem Benutzer zur leichten Bestätigung an (gemäß Empfehlung / zu single geändert / zu pack geändert).
Frage den Benutzer nach dem Installationsort und kopiere oder verlinke die kompilierten Artefakte dorthin.
Teile dem Benutzer mit: „Abgeschlossen. Du kannst es jetzt auf einen Schlag an darwin-skill für die automatische Evolution übergeben.“

Qualitäts-Rotlinien (Ausgabe blockieren bei Verstoß)

Jede Fähigkeit muss alle drei Validierungen bestehen.
Jede Fähigkeitskarte muss vollständige R-/I-/A1-/A2-/E-/B-Sechsteile haben; A1 ohne Originalbeispiel klar kennzeichnen; synthetische Übungen nicht als Tatsachen aus dem Buch ausgeben.
Zitate ≤150 Zeichen/Abschnitt (Englisch ≤100 Wörter/Abschnitt).
Jede aktive Fähigkeit hat in destinations.json genau ein Ziel (promoted_to oder served_by); nicht promotete Fähigkeiten müssen über den Quellen-Routing-Einstiegspunkt erreichbar sein.
Die description eines promoteten Skills muss die Auslösebedingungen klar angeben und sich durch benachbarte Negativbeispiele vom Quellen-Routing-Einstiegspunkt unterscheiden.
Das kompilierte Artefakt muss die Prüfung durch scripts/validate_skill_pack.py (Format/relative Referenzen/Frontmatter 100%) bestehen.
Das Zielverzeichnis ist schreibgeschützt: Bei Erkennung manueller lokaler Änderungen darf der Compiler nicht stillschweigend überschreiben (erzwinge eine von drei Optionen).
Die Abdeckung wichtiger Aufgaben muss nachvollziehbare Ziele haben; die tatsächliche Ausgabeprüfung und die Quellenprüfung werden getrennt dokumentiert. Bei erheblichen Lücken darf nur ein Entwurf mit klar gekennzeichnetem Umfang ausgeliefert werden, kein vollständiger Durchlauf.

Ökologische Positionierung zu nuwa-skill / darwin-skill

nuwa-skill: Destilliert Menschen (Denkweisen/Ausdrucks-DNA)
cangjie-skill (dieser Skill): Destilliert Bücher (Methodiken/Rahmenwerke/Prinzipien)
darwin-skill: Evolviert jeden beliebigen Skill

Die drei greifen ineinander: Die Testfälle, die dieser Skill ausgibt, folgen dem darwin-skill-Format, sodass die produzierten Skills direkt an darwin zur automatischen Evolution angeschlossen werden können.

Aufrufkonventionen

Immer zuerst 1 Pilotbuch – es sei denn, der Benutzer sagt explizit „Batch“.
Zwischen den Phasen aktiv Fortschritt melden – nicht still durchlaufen und dann Ergebnisse ausgeben.
Nicht aus dem Gedächtnis destillieren – wenn kein Text vorhanden ist, innehalten und nachfragen.
Prüfprotokoll aufbewahren – candidates/ und rejected/ müssen erhalten bleiben.
Jederzeit wieder aufnehmbar – nach jeder Phase PIPELINE_STATE.md aktualisieren, bei Unterbrechung vom Statusfile aus fortsetzen.
Ausgabestrategie persistent – update/repair verwendet standardmäßig das ursprüngliche Ausgabeformat; neue Materialien verändern die Produktform nicht stillschweigend.

firelive/agent-skills

Was ist agent-skills?

In Ihrer bevorzugten KI fragen

Dokumentation