Wie skill.md den gesamten Ablauf steuert: Modi-Erkennung, Phasen-Sequenzen für Kurs- und Verstehen-Pipeline, Fehlerbehandlung und Retry-Logik.
Der Orchestrator ist der zentrale Steuerungsmechanismus in skill.md. Er bestimmt, welcher Modus aktiv ist, welche Phasen in welcher Reihenfolge durchlaufen werden und welche Qualitäts-GatesPrüfpunkte zwischen Phasen, die sicherstellen, dass alle Voraussetzungen für die nächste Phase erfüllt sind. Beispiel: "Alle Batch-Ergebnisse vorhanden?" vor dem Assemble-Schritt. eingehalten werden müssen.
# skill.md — Orchestrator-Logik (vereinfacht)
orchestrator:
mode_detection:
strategy: "keyword_match"
fallback: "ask_user"
keywords:
course: ["Kurs", "Tutorial", "HTML", "course", "lernen"]
understand: ["verstehen", "graph", "analyze", "KG"]
combined: ["beides", "kombiniert", "alles", "both"]
phase_contract:
each_phase_must:
- declare inputs (files, context)
- declare outputs (files, data)
- pass quality gate before next phase
- handle errors with retry or partial result
Wie funktioniert die Modi-Erkennung? Der Orchestrator analysiert die Benutzereingabe auf Schlüsselwörter. "Erstelle einen Kurs" aktiviert den Kurs-Modus, "Verstehe dieses Projekt" den Verstehen-Modus. Bei Mehrdeutigkeit fragt der Skill nach.
Phase-Vertrag: Jede Phase definiert exakt, welche Inputs sie braucht und welche Outputs sie erzeugt. Erst wenn das Qualitäts-Gate bestanden ist, startet die nächste Phase. Das verhindert Kaskadierfehler.
Die Weichenstellung erfolgt einmalig am Anfang. Danach läuft die gewählte Pipeline sequenziell durch. Der Orchestrator überwacht den Fortschritt, protokolliert Warnungen und kann bei Bedarf einzelne Phasen wiederholen.
Die Kurs-Pipeline transformiert eine Codebase in interaktive HTML-Kurse. Jede Phase baut auf den Ergebnissen der vorherigen auf:
| Phase | Name | Input | Output | Gate |
|---|---|---|---|---|
| P0 | Bootstrap | Projektpfad, User-Antworten | Datei-Inventar, Dir-Tree, README-Inhalt | Inventar ≥ 1 Datei |
| P1 | Analyse | Inventar, Dateien | Tech-Stack, Patterns, Abhängigkeiten | Stack erkannt |
| P2 | Curriculum | Analyse-Ergebnis, Zielgruppen | Themen-Liste mit HS pro Zielgruppe | Mind. 3 Themen HS≥6 |
| P3 | Foundation | Curriculum, Design-System | index_*.html (L0-Dateien) | Alle L0-Dateien valide |
| P4 | Build | Curriculum, L0-Links | L1/, L2/, L3/ HTML-Dateien | Alle Links auflösbar |
| P5 | Polish | Alle generierten Dateien | Korrigierte Dateien, Cross-Links | 0 broken Links |
| P6 | Tiefenkarte | Vollständige Dateiliste | Visuelle Sitemap mit Verlinkungen | Alle Seiten erfasst |
# Phase 2: Curriculum — HS-Bewertung pro Thema
curriculum:
topics:
- name: "Skill-Architektur"
hs_anwender: 4 # zu technisch → kein Anwender-L1
hs_entwickler: 9 # ≥8 → L1 + Deep-Dive auf L2
- name: "Kurs erstellen"
hs_anwender: 9 # ≥8 → L1 + Deep-Dive auf L2
hs_entwickler: 5 # <6 → nicht im Entwickler-Kurs
- name: "Graph Schema"
hs_entwickler: 7 # 6-7 → L1 + L2, aber KEIN L3
# Regeln:
# HS < 6 → Thema nicht aufgenommen
# HS 6-7 → L1-Seite, L2-Seite, kein Deep-Dive auf L3
# HS ≥ 8 → L1 + L2 + Deep-Dive-Link auf L3
Helpfulness-Score (HS): Jedes Thema wird pro Zielgruppe bewertet. Ein HS von 9 bedeutet "extrem hilfreich", ein HS von 3 bedeutet "kaum relevant". Die Schwellenwerte bestimmen, wie tief ein Thema im Kurs behandelt wird.
Beispiel: "Skill-Architektur" ist für Entwickler hochrelevant (HS=9), für Anwender aber zu technisch (HS=4). Daher erscheint dieses Thema nur im Entwickler-Kurs mit Deep-Dive, nicht im Anwender-Kurs.
Die Verstehen-Pipeline erzeugt einen Knowledge GraphEine JSON-Struktur mit Nodes (Dateien, Funktionen, Klassen), Edges (imports, calls, contains), Layers (Architektur-Schichten) und einer Guided Tour (Lernpfad). anstatt HTML-Kurse. Sie hat eine Phase mehr, weil der Graph-Merge und die Architektur-Erkennung zusätzliche Schritte erfordern:
| Phase | Name | Agenten | Output |
|---|---|---|---|
| P0 | Pre-flight | — | Projektpfad validiert, .claude-learning/ erstellt |
| P1 | Scan | project-scanner | Datei-Inventar, Import-Map, Dir-Tree |
| P2 | Analyze | file-analyzer (5x parallel) | Batch-JSONs mit Nodes + Edges |
| P3 | Assemble | assemble-reviewer | Merged Graph (deduplizierte Nodes/Edges) |
| P4 | Architecture | architecture-analyzer | Layer-Zuordnung (Frontend, Backend, DB...) |
| P5 | Tour | tour-builder | Guided Tour mit geordnetem Lernpfad |
| P6 | Review | review-validator | Validierter Graph, Fehler-Log |
| P7 | Save | — | knowledge-graph.json + dashboard.html |
Der kritische Unterschied zur Kurs-Pipeline: Phase 2 (Analyze) läuft parallel mit bis zu 5 file-analyzer-Instanzen gleichzeitig. Jede Instanz bearbeitet einen Batch von 20-30 Dateien und erzeugt ein Batch-JSON. In Phase 3 werden alle Batch-Ergebnisse zu einem konsistenten Graph zusammengeführt.
Der Kombiniert-Modus führt zuerst die komplette Verstehen-Pipeline aus (Phase A), nutzt dann den erzeugten Knowledge Graph als zusätzlichen Input für die Kurs-Pipeline (Phase B). Das Ergebnis: Kurse, die durch Graph-Daten angereichert sind.
# Kombiniert-Pipeline in skill.md
combined_pipeline:
phase_a: # Verstehen-Pipeline komplett
phases: [A0, A1, A2, A3, A4, A5, A6, A7]
output: .claude-learning/knowledge-graph.json
gate: "Graph hat ≥10 Nodes, ≥5 Edges"
phase_b: # Kurs-Pipeline mit KG-Enhancement
phases: [B0, B1, B2, B3, B4, B5, B6]
extra_input: knowledge-graph.json
enhancements:
- "HS-Scoring berücksichtigt Graph-Zentralität"
- "Kurs-Diagramme nutzen echte Edge-Daten"
- "Tour-Reihenfolge beeinflusst L1-Anordnung"
Warum kombiniert? Ohne Knowledge Graph basiert das Curriculum-Scoring auf heuristischer Analyse. Mit Graph-Daten kann der Scoring-Algorithmus die tatsächliche Zentralität von Komponenten berücksichtigen — zentrale Module bekommen höhere Scores.
Konkrete Verbesserungen: Architektur-Diagramme in den Kursseiten zeigen echte Import-Ketten statt geschätzter. Die Reihenfolge der L1-Themen folgt der Tour-Logik des Graphs. Edge-Gewichte beeinflussen, welche Abhängigkeiten erklärt werden.
Die Phasen werden mit Präfix A bzw. B benannt, um Verwechslungen zu vermeiden. Phase A3 ist der Assemble-Schritt der Verstehen-Pipeline, Phase B2 ist das Curriculum der Kurs-Pipeline. Die Gate zwischen A und B stellt sicher, dass der Graph mindestens 10 Nodes und 5 Edges enthält — andernfalls fällt der Skill zurück auf den reinen Kurs-Modus.
Nicht jede Phase läuft fehlerfrei. Der Orchestrator implementiert eine dreistufige Fehlerbehandlung, die Robustheit über Perfektion stellt:
# Fehlerbehandlung in skill.md
error_handling:
retry:
max_attempts: 2
applies_to: [P2_analyze, P3_assemble]
strategy: "reduce_batch_size"
partial_results:
enabled: true
min_coverage: 0.6 # 60% der Dateien müssen analysiert sein
warning: "⚠ {n} Dateien konnten nicht analysiert werden"
phase_warnings:
collect: true
display: "end_of_pipeline"
categories:
- "missing_edges" # Referenzierte Nodes fehlen
- "orphan_nodes" # Nodes ohne Verbindungen
- "broken_links" # HTML-Links zeigen ins Leere
- "low_hs_threshold" # Wenige Themen über HS 6
Retry-Logik: Wenn ein file-analyzer-Batch fehlschlägt (z.B. bei zu großen Dateien), wird der Batch halbiert und erneut versucht. Maximal 2 Versuche pro Phase. Danach greift Partial Results.
Partial Results: Wenn mindestens 60% der Dateien erfolgreich analysiert wurden, fährt die Pipeline fort — mit einer Warnung. Nur bei weniger als 60% bricht die Pipeline ab.
Phase Warnings: Nicht-kritische Probleme werden gesammelt und am Ende der Pipeline angezeigt. Fehlende Edges oder verwaiste Nodes verhindern nicht den Abschluss, werden aber dokumentiert.
Diese Architektur stellt sicher, dass selbst bei problematischen Codebases (fehlende Importe, zirkuläre Abhängigkeiten, binäre Dateien) ein brauchbares Ergebnis entsteht. Der Benutzer sieht am Ende eine klare Zusammenfassung: Was wurde generiert, was fehlt, und warum.
skill.md-Aufbau vertiefen