Wie ich mit Claude Skills meine ersten Code-Tutorials automatisiert habe

Die automatische Generierung von Entwickler-Tutorials aus bestehendem Code ist ein ambitioniertes Projekt – doch genau das hat der Softwareentwickler Shahid Shaaf mit seinem Open-Source-Tool Waver umgesetzt. Sein Ansatz verbindet Java-basierte Optimierungen mit modernen Sprachmodellen, um verständliche Markdown-Tutorials inklusive Mermaid-Diagrammen zu erstellen. Dabei entdeckte er nicht nur die Grenzen klassischer LLM-Ketten, sondern entwickelte parallel JGraphlet, ein Framework zur effizienteren Steuerung von Aufgabenpipelines. Sein jüngstes Experiment mit Claude Skills zeigt nun, wie sich diese Konzepte in einer modularen Skill-Architektur konsolidieren lassen – mit vielversprechenden ersten Ergebnissen.

Die Evolution von Waver: Von promptbasierten Pipelines zu Skills

Shaafs ursprüngliches Projekt Waver nutzte LangChain4J, um aus Codebasen Schritt-für-Schritt-Tutorials zu generieren. Die Architektur bestand aus einer Reihe sequenzieller Aufgaben – von der Codeanalyse bis zur finalen Dokumentation – die über eine TaskPipeline orchestriert wurden. Ein zentrales Problem blieb jedoch die Performance-Optimierung bei der Kommunikation mit Sprachmodellen, was ihn zur Entwicklung von JGraphlet inspirierte.

Mit der Einführung von Claude Skills hat Shaaf nun einen modularen Ansatz gewählt, der die Prompts direkt in Skill-Komponenten auslagert. Statt starrer Ketten (Chain-of-Thought) setzt er auf prompt chaining, bei dem jede Aufgabe durch eine eigene Skill-Instanz definiert ist. Erste Tests mit dem Scribe-Codebase – einem MCP-Server-Projekt – belegen, dass diese Struktur nicht nur die Wartbarkeit verbessert, sondern auch präzisere Mermaid-Diagramme erzeugt.

Ein Beispiel aus der Praxis zeigt die generierte Abhängigkeitsstruktur von Scribe als Mermaid-Graph:

graph TD
  KantraTool[KantraTool<br/>MCP Server Entry Point] -->|queries availability| CommandRegistry[CommandRegistry<br/>Plugin System]
  KantraTool -->|invokes execute| KantraCommand[KantraCommand<br/>Command Interface]
  KantraTool -->|accepts as parameter| KantraOperation[KantraOperation<br/>Operation Catalog]
  CommandRegistry -->|discovers via CDI| KantraCommand
  CommandRegistry -->|uses as map key| KantraOperation
  CommandRegistry -->|applies filtering| CommandConfig[Configuration System]
  KantraCommand -->|declares operation| KantraOperation
  ConcreteCommands[Concrete Command<br/>Implementations] -->|extends| AbstractCommand[AbstractCommand<br/>Command Base Class]
  ConcreteCommands -->|constructs| Rule[Rule<br/>Domain Model]
  ConcreteCommands -->|creates instances| Condition[Condition<br/>Polymorphic Detection]
  AbstractCommand -->|delegates serialization| RuleValidator[RuleValidator<br/>Validation Service]
  AbstractCommand -->|converts to enums| DomainEnums[Domain Enumerations<br/>JavaLocation, Category]
  AbstractCommand -->|constructs| SupportingModels[Supporting Model Classes<br/>Link, CustomVariable]
  Rule -->|contains when field| Condition
  Rule -->|uses category| DomainEnums
  Rule -->|composes| SupportingModels
  Condition -->|references| DomainEnums
  Condition -->|contains| SupportingModels
  RuleValidator -->|validates & serializes| Rule
  RuleValidator -->|validates recursively| Condition

  style KantraTool fill:#e1f5ff,stroke:#0066cc,stroke-width:3px
  style Rule fill:#fff4e1,stroke:#ff9900,stroke-width:2px
  style Condition fill:#fff4e1,stroke:#ff9900,stroke-width:2px
  style CommandRegistry fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
  style RuleValidator fill:#e8f5e9,stroke:#4caf50,stroke-width:2px

Die Struktur einer Claude Skill: Modularität als Schlüssel

Claude Skills folgen einem definierten Dateisystem, das Entwickler:innen Klarheit über die Komponenten einer Skill-Implementierung gibt. Die wichtigsten Dateien und Ordner sind:

• `SKILL.md`: Hauptdatei mit Skill-Definition und Anweisungen für das Sprachmodell.
• `package.json`: NPM-Konfiguration zur Abhängigkeitsverwaltung.
• `installer.js`: Skript für die Skill-Installation.
• `bin/`: Ausführbare Befehle für die Skill-Aktivierung.
• `tests/`: Testprojekte in verschiedenen Sprachen, um die Generierungsergebnisse zu vergleichen.

Die SKILL.md bildet das Herzstück und enthält detaillierte Prompts für jede Phase der Tutorial-Generierung. Ein Ausschnitt aus dem Abschnitt zur Code-Discovery zeigt, wie der Skill Nutzer:innen durch den Analyseprozess führt:

1. Projektdetails ermitteln:

• Nutzerangaben priorisieren (z. B. tutorial analyze ./src).
• Falls kein Pfad angegeben: Nachfragen „Welches Verzeichnis soll analysiert werden?“
• Automatische Erkennung der Hauptsprache anhand von Dateiendungen.
• Optionale Eingrenzung auf bestimmte Bereiche.

1. Quelldateien finden:

• Java: **/*.java (Ausschlüsse: test/, target/)
• Python: **/*.py (Ausschlüsse: __pycache__/, venv/)
• JavaScript/TypeScript: **/*.{js,ts,jsx,tsx} (Ausschlüsse: node_modules/, dist/)
• Go: **/*.go (Ausschlüsse: _test.go, vendor/)

1. Große Codebasen handhaben:

• Bei mehr als 50 Dateien: „Gefunden {N} Dateien. Alle analysieren oder auf Unterverzeichnisse eingrenzen?“
• Vorschlag der Kernverzeichnisse wie src/main.

Shaaf betont, dass diese Struktur nicht nur die Entwicklererfahrung verbessert, sondern auch die Wiederverwendbarkeit der Skills steigert. Jede Skill-Komponente kann unabhängig getestet und optimiert werden, was die Wartung langfristig erleichtert.

Herausforderungen und Lessons Learned

Trotz der vielversprechenden Ergebnisse gab es Hürden, die Shaaf während der Entwicklung identifizierte:

• Prompts als Single Point of Failure: Lange, monolithische Prompts neigen zu Inkonsistenzen. Die Aufteilung in Skill-spezifische Module reduziert dieses Risiko.
• Performance vs. Flexibilität: Java-basierte Optimierungen (wie in JGraphlet) bieten zwar Kontrolle, erfordern aber mehr Aufwand bei Änderungen. Claude Skills hingegen punkten mit schneller Anpassbarkeit – auf Kosten von Deep-Linking-Optimierungen.
• Sprachmodell-Konfiguration: Die Auswahl des richtigen Modells (z. B. über ModelProviderFactory) bleibt kritisch. Shaaf experimentiert hier weiterhin mit verschiedenen Anbietern, um die Generierungsqualität zu verbessern.

Ein zentraler Vorteil der Skill-Architektur ist die Transparenz. Statt undurchsichtiger Ketten von LLM-Aufrufen können Entwickler:innen nun jede Komponente einzeln analysieren und verbessern. Dies beschleunigt nicht nur die Fehlerbehebung, sondern ermöglicht auch eine gezieltere Optimierung der Prompts.

Ausblick: Claude Skills als Game-Changer für die Tutorial-Automatisierung?

Shaafs Experiment mit Claude Skills zeigt, dass die Modularisierung von LLM-basierten Workflows neue Möglichkeiten eröffnet – besonders für Open-Source-Projekte. Während klassische Ansätze wie LangChain weiterhin ihre Berechtigung haben, bieten Skills eine niedrigschwellige Alternative, die auch Entwickler:innen ohne tiefes Prompt-Engineering-Wissen zugänglich ist.

Der nächste Schritt für Waver könnte die Integration weiterer Programmiersprachen oder die Erweiterung der Skill-Bibliothek um vorgefertigte Templates sein. Langfristig könnte diese Herangehensweise nicht nur die Tutorial-Generierung revolutionieren, sondern auch andere Bereiche der Software-Dokumentation automatisieren – von API-Dokumentationen bis hin zu Release-Notes.

Für Entwickler:innen, die ähnliche Projekte planen, rät Shaaf: „Beginne klein, aber denke modular. Die größte Stärke von Skills liegt in ihrer Flexibilität – nutze sie, um iterativ zu optimieren.“