Das 3000-Zeilen-Hirn des Learning Skills, Zeile fur Zeile. YAML-Frontmatter, Modus-Erkennung, Helpfulness-Scoring, Design-System, Agent-Dispatch.
skill.md beginnt mit einem YAML-FrontmatterDer Block zwischen zwei --- am Dateianfang. Claude liest diesen Block um den Skill-Namen und die Beschreibung zu erkennen. Ohne diesen Block wird die Datei nicht als Skill erkannt.-Block. Dieser Block definiert den Skill-Namen und eine kompakte Beschreibung, die Claude beim Laden des Skills als erstes sieht.
# Zeile 1-4: YAML-Frontmatter
---
name: learning-skill
description: Kombiniert zwei Superkraefte: (1) Verwandelt
Codebases in interaktive Multi-Level-HTML-Kurse (L0-L3)
mit Zielgruppen-Segmentierung und Energiekonzern-Design,
UND (2) erzeugt interaktive Knowledge Graphs mit Dashboard
zur Code-Exploration. DREI MODI: "Kurs" fuer HTML-Kurse,
"Verstehen" fuer Knowledge Graphs, "Kombiniert" fuer beides.
---
name: Der Slug learning-skill wird intern als Identifier verwendet. Er taucht in Ordnernamen und Referenzen auf.
description: Die Beschreibung ist bewusst lang und schluesselwortreich. Claude nutzt sie um zu entscheiden ob dieser Skill zum User-Prompt passt. Jedes Schluesselwort ("HTML-Kurse", "Knowledge Graphs", "Dashboard") erhoht die Match-Wahrscheinlichkeit.
Kein model:-Feld: Anders als bei Agent-Definitionen (die model: inherit haben) hat skill.md kein model-Feld -- der Skill laeuft immer im Kontext des aktuellen Modells.
Direkt nach dem Frontmatter folgt die IdentitatsregelEine Tabelle mit VERBOTENEN Begriffen wie "Understand Anything" oder "Understanding Skill". Diese Regel verhindert, dass der urspruengliche Projektname in irgendeinem Output erscheint. -- der wichtigste Compliance-Block des gesamten Skills.
## IDENTITAETS-REGEL — KEINE EXTERNEN PROJEKTNAMEN (HARD BLOCK)
VERBOTEN — in JEGLICHEM generierten Output:
| Verboten | Warum |
| "Understand Anything" | Externer Projektname |
| "Understand-Anything" | Externer Projektname |
| "Understanding Skill" | Falscher Name |
| "Claude Learning & Understanding Skill" | Falscher Name |
| "claude-learning-understanding" | Falscher Slug |
| ".understand-anything/" | Falscher Ordnername |
KORREKTE Bezeichnungen:
| Kontext | Korrekter Name |
| Skill-Name | "Learning Skill" |
| Skill-Slug | "learning-skill" |
| Output-Ordner | ".claude-learning/" |
| Modus-Bezeichnungen | "Kurs-Modus", "Verstehen-Modus" |
Warum existiert diese Regel? Der Learning Skill ist aus einem fruheren Projekt ("Understand Anything") hervorgegangen. Da der alte Name in keinem Output mehr erscheinen darf, prueft der Selbst-Check vor JEDEM Output auf diese verbotenen Strings.
Selbst-Check: 5 Pruefungen werden vor jedem generierten Output durchlaufen. Jede Pruefung ist ein Regex-Match auf den generierten Text. Wenn ein verbotener String gefunden wird, muss er entfernt oder ersetzt werden.
# Der Selbst-Check: 5 Pruefungen vor JEDEM Output
Selbst-Check vor JEDEM Output:
[ ] Enthaelt der Output den String "Understand Anything"?
-> ENTFERNEN
[ ] Enthaelt der Output den String "Understanding"?
-> Nur OK wenn generisches Wort in Satz
(z.B. "for understanding the code")
NICHT OK als Namensbestandteil
[ ] Enthaelt der Output ".understand-anything/"?
-> ERSETZEN durch ".claude-learning/"
[ ] Enthaelt eine Commit-Message einen Hinweis
auf externe Projekte?
-> ENTFERNEN
[ ] Enthaelt der Output "aus Understand-Anything"?
-> ENTFERNEN
git commit -m "merge from understand-anything" wuerde die Regel verletzen. Dies wird oft uebersehen weil Entwickler Debug-Output nicht als "generierten Output" betrachten.
Die Modus-Erkennung ist der erste Entscheidungspunkt. Sie liest den User-PromptDie erste Nachricht des Users die den Skill aktiviert. Enthaelt typischerweise einen Pfad/URL und Schluesselwoerter wie "Kurs", "verstehen" oder "beides". und matcht Schluesselwoerter gegen drei Modus-Tabellen. Falls kein eindeutiger Match: Rueckfrage.
# Modus-Erkennung: Schluesselwort-Matching
| Modus | Schluesselwoerter |
| Kurs-Modus | "Kurs", "Tutorial", "Walkthrough", |
| | "interaktiv", "course", "teach", |
| | "lernen", "erklaeren", "HTML", |
| | "Kursseiten" |
| Verstehen-Modus| "verstehen", "understand", |
| | "knowledge graph", "dashboard", |
| | "explore", "graph", "analyse", |
| | "analyze" |
| Kombiniert | "beides", "komplett", "full", |
| | "alles", "combined", "kurs + graph", |
| | "everything" |
| Unklar | Keines der obigen |
| | -> User fragen! |
Kurs-Modus: Aktiviert die HTML-Kurs-Pipeline (Phasen 0-6). Erzeugt Self-Contained HTML-Dateien mit Level-Hierarchie.
Verstehen-Modus: Aktiviert die Knowledge-Graph-Pipeline (Phasen 0-7). Erzeugt knowledge-graph.json + React-Dashboard.
Kombiniert: Erst KG-Pipeline, dann KG-gestuetztes Kurs-Building. Die KG-Daten verbessern das Helpfulness-Scoring.
Unklar: Die sicherste Option -- lieber einmal zu viel fragen als falsch bauen.
Nach der Modus-Erkennung kommt der HARD BLOCKEine unumgehbare Sperre: Phase 1 darf NICHT starten bevor der User Zielgruppen UND Integrationsmodus explizit beantwortet hat. Keine Ausnahme -- auch nicht bei "teste den Skill" oder "mach einfach".: Zwei Weichen muessen VOM USER beantwortet sein.
# HARD BLOCK: Selbst-Check vor Phase 1
# Dieser Check wird NACH der Modus-Erkennung ausgefuehrt
# und BEVOR irgendein HTML generiert wird.
Selbst-Check vor Phase 1:
[ ] Hat der User EXPLIZIT gesagt fuer welche
Zielgruppen?
-> Wenn nein: FRAGEN
[ ] Hat der User EXPLIZIT gesagt ob
Standalone oder Eingebettet?
-> Wenn nein: FRAGEN
[ ] Wenn Eingebettet: Hat der User
GitHub-URL, Impressum, Datenschutz, Copyright
angegeben?
-> Wenn nein: NACHFRAGEN
[ ] Alle drei Checks bestanden?
-> Erst jetzt Phase 1 starten
Die Rueckfrage selbst ist ein vordefiniertes Template, das dem User drei Zielgruppen-Optionen mit ihren Standard-Tiefen zeigt:
# Rueckfrage-Template (wird an den User gesendet)
Bevor ich loslege, zwei Fragen:
1. Fuer wen ALLES soll der Kurs sein?
* Anwender -- Leute die die App BENUTZEN wollen
(Default: bis L2, Fokus auf Workflows)
* Entwickler -- Leute die den Code VERSTEHEN wollen
(Default: bis L3, volle Tiefe)
* Entscheider-- Management, Stakeholder
(Default: bis L1, kompakt + KPIs)
* Andere -- eigene Zielgruppe definieren
(Default: bis L2, anpassbar)
2. Wie werden die Kurse genutzt?
* Standalone -- Dateien zum Teilen/Offline-Nutzen
* Eingebettet -- Teil einer Website
(dann brauche ich: GitHub-Link?
Impressum-URL? Copyright?)
| User sagt | Weiche 1 (ZG) | Weiche 2 (Integration) | Aktion |
|---|---|---|---|
| "Fuer Devs, standalone" | Klar | Klar | Phase 1 starten |
| "Mach einen Kurs" | Unklar | Unklar | Volle Rueckfrage |
| "Fuer Entwickler" | Klar | Unklar | Nur Weiche 2 fragen |
| "Standalone bitte" | Unklar | Klar | Nur Weiche 1 fragen |
| "Teste das mal" | Unklar | Unklar | Volle Rueckfrage |
Nicht jedes Thema verdient 3 weitere Ebenen. Der Helpfulness-ScoreEine Zahl von 1-10 die bewertet, ob eine tiefere Seite dem Lernenden WIRKLICH hilft. Berechnet aus 4 Dimensionen: Komplexitaet, Relevanz, Lernwert, Eigenstaendigkeit. (HS) entscheidet autonom, ob ein Thema eine eigene Unterseite bekommt oder als Absatz auf der Eltern-Seite bleibt.
# Helpfulness-Score Formel
HS = Komplexitaet(0-3) + Relevanz(0-3)
+ Lernwert(0-2) + Eigenstaendigkeit(0-2)
# Maximal erreichbar: 3+3+2+2 = 10
| Dimension | 0 | 1 | 2 | 3 |
| Komplexitaet | Trivial, | Braucht | Braucht mehrere | Braucht eigene |
| | 1 Satz | 1 Absatz | Abschnitte | Seite mit Visuals |
| Relevanz | Nischen- | Nice-to-know | Wichtig fuer | Kern-Konzept, |
| | Detail | | Verstaendnis | ohne das nichts geht |
| Lernwert | Nur Fakten | Erklaert | Ermoeglicht | n/a (max 2) |
| | | ein "Warum" | eigenes Handeln | |
| Eigenstaendigkeit | Wiederholung| 50% neue | 80% neue | n/a (max 2) |
| | v. Eltern | Information | Information | |
Komplexitaet (0-3): Wie viel Erklaerungsaufwand braucht das Thema? Ein trivialer Fakt (0) vs. ein Konzept das Visualisierungen braucht (3).
Relevanz (0-3): Wie zentral ist das Thema fuer das Verstaendnis des Gesamtsystems? Ein Nischen-Detail (0) vs. ein unverzichtbares Kern-Konzept (3).
Lernwert (0-2): Was KANN der Lernende nach dem Lesen tun? Nur Fakten kennen (0) vs. selbst handeln koennen (2).
Eigenstaendigkeit (0-2): Wie viel NEUES bringt eine eigene Seite? Wenn 80%+ Wiederholung der Eltern-Seite, lohnt sich keine eigene Seite.
Entscheidend: Die Schwellenwerte sind nicht fuer alle Zielgruppen gleich. Jede Zielgruppe hat ihr eigenes TiefenprofilDefiniert Max-Level, HS-Schwelle fuer eigene Seite und HS-Schwelle fuer "noch tiefer" pro Zielgruppe. Entscheider brauchen selten mehr als L1, Entwickler gehen bis L3.:
# Zielgruppenspezifische Schwellenwerte
| Zielgruppe | Max-Level | HS eigene Seite | HS noch tiefer |
| Anwender | L2 | >= 7 (streng) | >= 9 |
| Entwickler | L3 | >= 6 (Standard) | >= 8 |
| Entscheider | L1 | >= 8 (strengst) | >= 10 (nie) |
# Entscheidungsbaum pro Thema T, Zielgruppe Z, Level L:
1. L >= max_level[Z]? -> STOPP.
Kein tieferes Level.
2. HS(T,Z) < hs_schwelle[Z]? -> Kein eigene Seite.
Absatz/Aufklapp auf Eltern.
3. HS(T,Z) >= hs_schwelle[Z]? -> Eigene Seite.
4. HS(T,Z) >= hs_tiefer[Z] -> Pruefe L+1.
UND L+1 < max_level[Z]? Wenn ja: L+1 planen.
Derselbe HS kann fuer verschiedene Zielgruppen voellig unterschiedliche Ergebnisse liefern. Hier die Zielgruppen-Gewichtung pro Thema-Typ:
# Zielgruppen-Gewichtung: Gleiches Thema, anderer HS
| Thema-Typ | Anwender | Entwickler | Entscheider |
| Implementierungsdetail | 1-3 | 7-10 | 1-3 |
| UI-Workflow | 7-10 | 3-5 | 2-4 |
| Kosten/ROI | 2-4 | 1-3 | 8-10 |
| Fehlerbehandlung | 6-8 | 8-10 | 3-5 |
| Architektur-Entscheid. | 1-3 | 7-9 | 6-8 |
| Sicherheit/Compliance | 3-5 | 7-9 | 8-10 |
# Beispiel: Thema "Authentifizierung"
Anwender: HS=7 -> L1 eigene Seite, kein L2 (7 < 9)
Entwickler: HS=9 -> L1 + L2 + L3 (9 >= 8, bis Max L3)
Entscheider:HS=8 -> L1 nur (Max-Level L1 erreicht)
complexity: "complex" erhalten +1 Bonus auf Komplexitaet. Nodes mit Fan-in > 5 erhalten +1 auf Relevanz. Core-Layer-Nodes erhalten +1 auf Lernwert. Der finale HS wird auf max(10) gedeckelt: final_HS = min(10, base_HS + kg_bonus).
Phase 3 (FOUNDATION) definiert das Design-System als Inline-CSSEs gibt KEINE separate CSS-Datei. Alles ist inline in jeder HTML-Datei (Self-Contained-Prinzip). Das CSS wird einmal definiert und in jede Datei kopiert um Konsistenz zu gewaehrleisten.. Der :root-Block ist das Herzstuck -- er definiert 60+ Custom Properties die in jeder Seite identisch sind.
:root {
/* === PRIMAERE BRAND-FARBEN === */
--color-deep-blue: #000099;
--color-impulse-orange: #FE8F11;
--color-warm-gray: #E4DAD4;
/* === HINTERGRUENDE === */
--color-bg: #FFFFFF;
--color-bg-warm: #F3EFEB;
--color-bg-code: #000066;
/* === TEXT === */
--color-text: #1A1A2E;
--color-text-secondary: #6B6560;
--color-text-muted: #7A7570;
/* WCAG AA: 5.1:1 auf Weiss */
/* === SEMANTISCHE FARBEN === */
--color-success: #84C041;
--color-error: #CC0000;
--color-info: #1195EB;
--color-warning: #FDC83A;
/* === AKTEUR-FARBEN (6 Farben) === */
--color-actor-1: #000099; /* Deep Blue */
--color-actor-2: #FE8F11; /* Impulse Orange */
--color-actor-3: #84C041; /* Success Green */
--color-actor-4: #1195EB; /* Info Blue */
--color-actor-5: #5BE3D6; /* Teal */
--color-actor-6: #FDC83A; /* Warning Yellow */
/* === FONTS === */
--font-display: 'Bricolage Grotesque', Georgia, serif;
--font-body: 'DM Sans', -apple-system, sans-serif;
--font-mono: 'JetBrains Mono', 'Fira Code', monospace;
/* === TYPOGRAFIE === */
--text-xs:.75rem; --text-sm:.875rem;
--text-base:1rem; --text-lg:1.125rem;
/* ... bis --text-6xl: 3.75rem */
/* === LAYOUT === */
--content-width: 820px;
--content-width-wide: 1000px;
--nav-height: 50px;
}
Primaere Brand-Farben: Drei Kernfarben bilden die "Energiekonzern-Palette". Deep Blue (#000099) fuer Vertrauen und Expertise, Impulse Orange (#FE8F11) fuer Aufmerksamkeit und CTAs, Warm Gray (#E4DAD4) fuer Borders und dezente Trennungen.
Code-Hintergrund: #000066 (dunkler als Deep Blue) sorgt fuer ausreichend Kontrast zu hellem Code-Text (Ratio >7:1, WCAG AAA).
Text-Muted: #7A7570 hat ein Kontrastverhaltnis von 5.1:1 auf Weiss -- gerade so WCAG AA konform. Fuer laengere Texte sollte --color-text (#1A1A2E, 15.7:1) bevorzugt werden.
Akteur-Farben: 6 distinkte Farben fuer Flow-Diagramme und Architektur-Visualisierungen. Sie sind so gewaehlt, dass sie sich auch bei Farbenblindheit (Deuteranomalie) unterscheiden lassen.
Content-Width: 820px ist der goldene Schnitt fuer Lesbarkeit -- circa 70 Zeichen pro Zeile bei 1rem Schriftgroesse.
Die WCAG-Kontrast-Regeln sind im Design-System als harte Constraints verankert:
# WCAG AA Kontrast-Matrix (Minimum 4.5:1 fuer Text)
| Vordergrund | Hintergrund | Ratio | Status |
| --color-text (#1A1A2E) | #FFFFFF | 15.7:1 | AAA |
| --color-text (#1A1A2E) | --bg-warm | 13.2:1 | AAA |
| --color-text-muted | #FFFFFF | 5.1:1 | AA |
| rgba(255,255,255,.9) | --bg-code | 12.8:1 | AAA |
| --impulse-orange | --deep-blue | 4.7:1 | AA |
| --impulse-orange | #FFFFFF | 2.9:1 | Fail* |
* Orange auf Weiss failt WCAG AA fuer normalen Text.
Deshalb wird Orange nur fuer grosse Headlines (>=18px)
und Icons verwendet, NICHT fuer Body-Text.
@media (max-width: 768px) { :root { --text-4xl: 1.875rem; --text-5xl: 2.25rem; } }
@media (max-width: 480px) { :root { --text-4xl: 1.5rem; --text-5xl: 1.875rem; } }
Die Breakpoints sind 768px (Tablet) und 480px (Smartphone).
skill.md dispatcht zwei Arten von Sub-AgentsClaude-Instanzen die ueber das Task-Tool gestartet werden. Jeder Agent erhaelt sein eigenes Prompt-Template und arbeitet isoliert. Ergebnisse fliessen zurueck in den Haupt-Kontext.: Pipeline-Agents (1 pro Zielgruppe) und Datei-Agents (1 pro HTML-Datei). Beide werden ueber Template-Strings konfiguriert.
# Pipeline-Agent-Prompt-Template
# 1 Pipeline-Agent pro Zielgruppe
Du bist der Pipeline-Agent fuer die Zielgruppe
[EMOJI + NAME].
Tiefenprofil:
- Max-Level: [L1/L2/L3]
- HS-Schwelle eigene Seite: [>=6/>=7/>=8]
- HS-Schwelle noch tiefer: [>=8/>=9/>=10]
Integrationsmodus: [Standalone/Eingebettet]
Output-Verzeichnis: [PFAD]
Curriculum fuer deine Zielgruppe:
[THEMEN-BAUM MIT HS-SCORES NUR FUER DIESE ZG]
CSS/JS-Foundation: [REFERENZ AUF PHASE-3-OUTPUT]
Naming-Konvention:
- L0: index[_SUFFIX]_[de|en].html
- L1: l1/[slug][_SUFFIX]_[de|en].html
- L2: l2/[slug][_SUFFIX]_[de|en].html
- L3: l3/[slug][_SUFFIX]_[de|en].html
Deine Aufgabe:
1. Baue L0 (DE + EN parallel als Datei-Agents)
2. WARTE bis L0 fertig
3. Baue L1 — NUR Themen mit HS >= [SCHWELLE]
4. WARTE bis L1 fertig
5. [Wenn Max-Level >= L2:] Baue L2
6. WARTE bis L2 fertig
7. [Wenn Max-Level = L3:] Baue L3
8. Gib Pipeline-Zusammenfassung zurueck
Zeile 1-2: Der Agent erhaelt seine Zielgruppen-Identitaet -- inkl. Emoji fuer die interne Zuordnung in Logs.
Tiefenprofil: Die drei kritischen Parameter die bestimmen, wie tief die Pipeline geht. Der Agent kann NICHT ueber sein Max-Level hinaus bauen.
Curriculum: Hier wird der gefilterte Themen-Baum injiziert -- NUR die Themen fuer DIESE Zielgruppe. Ein Anwender-Pipeline-Agent sieht keine Entwickler-Themen.
Schritte 1-8: Die streng sequenzielle Abfolge INNERHALB der Pipeline. Zwischen den Levels wird GEWARTET. Innerhalb eines Levels laufen Datei-Agents parallel.
Wichtig: Zielgruppen-Switch-Links auf L0 bleiben LEER -- sie werden erst in Phase 5 (Polish) gesetzt, wenn ALLE Pipelines fertig sind.
# Datei-Agent-Prompt-Template
# 1 Datei-Agent pro HTML-Datei
Erstelle die HTML-Datei [DATEINAME]
im Verzeichnis [PFAD].
Kontext:
- Zielgruppe: [EMOJI + NAME]
- Sprache: [DE/EN]
- Level: [L0/L1/L2/L3]
- Thema: [THEMA]
- Integrationsmodus: [Standalone/Eingebettet]
- Helpfulness-Score: [SCORE]
Inhalt: [INHALTSBESCHREIBUNG AUS CURRICULUM]
CSS/JS: Verwende exakt das folgende Foundation:
[FOUNDATION EINFUEGEN ODER REFERENZ]
Verlinkung:
- Breadcrumb-Pfad: [PFAD]
- Deep-Dive-Links: [LISTE DER ZIEL-DATEIEN]
- Sibling-Seiten: [LISTE INNERHALB DIESER ZG]
- Sprach-Pendant: [DATEINAME]
- Zielgruppen-Switch: PLATZHALTER
(wird in Phase 5 befuellt)
Qualitaetsgates: [ALLE RELEVANTEN GATES]
DATEINAME + PFAD: Werden aus der Naming-Konvention berechnet: [thema-slug][_zg-suffix]_[sprache].html im richtigen Level-Ordner.
Kontext-Block: Der Datei-Agent erhaelt ALLES was er braucht um die Seite autark zu bauen -- Zielgruppe, Sprache, Level, Thema, Integration und HS.
Foundation: Entweder wird das komplette CSS/JS inline eingefuegt, oder eine Referenz auf die Phase-3-Ausgabe. In der Praxis wird meistens inline eingefuegt (Self-Contained).
Verlinkung: Alle Links werden explizit vorgegeben -- der Agent muss keine Pfade raten. Das verhindert tote Links.
Zielgruppen-Switch = PLATZHALTER: Der Datei-Agent KANN den Switch nicht befuellen, weil er nicht weiss welche anderen Pipelines existieren. Phase 5 ersetzt den Platzhalter nachtraeglich.
Das Context-Injection-MusterBei der Verstehen-Pipeline werden Sprach- und Framework-Dateien dynamisch an den Agent-Prompt angehaengt. Fuer jede erkannte Sprache wird die passende .md-Datei aus dem languages/-Ordner geladen. funktioniert bei der Verstehen-Pipeline aehnlich -- dort werden Sprach-Addenda und Framework-Addenda injiziert:
# Context-Injection fuer Verstehen-Pipeline Agenten
# Am Beispiel des file-analyzer Agents
1. Base-Template:
agents/file-analyzer.md wird geladen
2. Language Context Injection:
FUER JEDE erkannte Sprache (z.B. python, typescript):
Lade ./languages/<language-id>.md
Haenge an unter ## Language Context Header
Wenn Datei nicht existiert: skip silently
3. Framework Addendum Injection:
FUER JEDES erkannte Framework (z.B. Django, React):
Lade ./frameworks/<framework-id>.md
Haenge an nach Language Context
Wenn Datei nicht existiert: skip silently
4. Batch-spezifischer Kontext:
- Project root Pfad
- Batch-Index Nummer
- Pre-resolved Import-Daten (batchImportData)
- Liste der zu analysierenden Dateien
5. Finaler Prompt =
Base-Template
+ Language Context(s)
+ Framework Addendum(s)
+ Batch-Kontext
languages/*.md existiert (z.B. ein obskures Format), wird sie silently skipped. Der Agent arbeitet dann ohne Sprach-spezifische Hints. Dies kann zu generischeren Knoten-Summaries fuehren. Aktuell existieren 23 Sprach-Dateien und 10 Framework-Dateien.