Was wir beim Bau von Claude Code gelernt haben: Wie wir Skills einsetzen

• In Claude Code sind Skills einer der am häufigsten genutzten Erweiterungspunkte, und es werden praxiserprobte Erkenntnisse offengelegt, die aus dem realen Betrieb von Hunderten von Skills innerhalb von Anthropic stammen
• Skills sind keine bloßen Markdown-Dateien, sondern eine Ordnerstruktur, die Skripte, Assets, Daten usw. enthält, in einer Form, die der Agent durchsuchen und nutzen kann
• Sie werden in 9 Skill-Kategorien eingeordnet, darunter Bibliotheksreferenzen, Produktverifikation, Datenanalyse, Code-Scaffolding und CI/CD; ein guter Skill sollte klar in eine einzige Kategorie passen
• Beim Schreiben von Skills sind praktische Tipps wie ein Gotchas-Abschnitt, die Nutzung des Dateisystems, Progressive Disclosure und Datenspeicherung zentral
• Beim Skalieren in der Organisation wird empfohlen, Skills über einen internen Plugin-Marktplatz zu verteilen und ihre Wirkung mit Nutzungs-Mess-Hooks nachzuverfolgen

---

Was sind Skills?

• Ein verbreitetes Missverständnis über Skills ist, dass sie „einfach nur Markdown-Dateien“ seien, tatsächlich handelt es sich aber um eine Ordnerstruktur, die Skripte, Assets, Daten usw. enthält
• Der Agent kann diesen Ordner durchsuchen, Inhalte entdecken und bearbeiten
• In Claude Code bieten Skills verschiedene Konfigurationsoptionen, und auch die Registrierung dynamischer Hooks ist möglich
• Die interessantesten Skills sind jene, die diese Konfigurationsoptionen und die Ordnerstruktur kreativ nutzen

Die 9 Kategorien von Skills

• Nachdem alle intern verwendeten Skills klassifiziert wurden, ergaben sich Cluster aus einigen wiederkehrenden Kategorien
• Gute Skills passen sauber in eine einzige Kategorie, verwirrende Skills erstrecken sich über mehrere Kategorien

• 1. Library & API Reference

  • Skills, die erklären, wie Bibliotheken, CLI und SDKs korrekt verwendet werden
  • Ziel sind nicht nur interne Bibliotheken, sondern auch allgemeine Bibliotheken, bei denen Claude Code häufig Fehler macht
  • Häufig enthalten sie einen Ordner mit Referenz-Code-Snippets und eine Liste mit Fallstricken (Gotchas)
  • Beispiele: billing-lib(Randfälle einer internen Zahlungsbibliothek), internal-platform-cli(alle Subcommands des internen CLI-Wrappers und Nutzungsbeispiele), frontend-design(verbesserte Anwendung des Design-Systems)

• 2. Product Verification

  • Skills, die beschreiben, wie Code getestet und verifiziert wird, um korrektes Verhalten sicherzustellen
  • Sie werden oft in Kombination mit externen Tools wie Playwright oder tmux eingesetzt
  • Sehr nützlich, um die Korrektheit von Claudes Ausgaben sicherzustellen; es lohnt sich für Engineers, notfalls eine Woche zu investieren, um einen Verifikations-Skill hervorragend zu machen
  • Empfohlen werden Techniken, bei denen Claude seine Ausgabe als Video aufzeichnet oder in jedem Schritt programmatische Assertions zum Zustand erzwingt
  • Beispiele: signup-flow-driver(Registrierung → E-Mail-Bestätigung → Onboarding in einem Headless-Browser durchführen), checkout-verifier(Bezahl-UI mit Stripe-Testkarten ausführen und anschließend den Rechnungsstatus prüfen), tmux-cli-driver(für Tests interaktiver CLI-Programme, die ein TTY benötigen)

• 3. Data Fetching & Analysis

  • Skills, die sich mit Daten- und Monitoring-Stacks verbinden
  • Sie können Bibliotheken zum Datenabruf mit Zugangsdaten, bestimmte Dashboard-IDs und Anleitungen für typische Workflows enthalten
  • Beispiele: funnel-query(Tabellen mit den nötigen Events und der kanonischen user_id für den Funnel Registrierung → Aktivierung → Zahlung), cohort-compare(Vergleich von Retention/Konversionsraten zweier Kohorten und Kennzeichnung statistischer Signifikanz), grafana(Data-Source-UIDs, Clusternamen, Lookup-Tabelle Problem → Dashboard)

• 4. Business Process & Team Automation

  • Skills, die wiederkehrende Workflows mit einem einzigen Befehl automatisieren
  • Die Anweisungen sind vergleichsweise simpel, können aber komplexe Abhängigkeiten zu anderen Skills oder MCP haben
  • Wenn Ergebnisse früherer Ausführungen in Log-Dateien gespeichert werden, hilft das dem Modell, konsistent zu bleiben und frühere Läufe einzubeziehen
  • Beispiele: standup-post(formatiertes Standup aus Ticket-Tracker, GitHub-Aktivität und Slack), create-ticket(Workflow mit Schema-Erzwingung und Erstellung), weekly-recap(Post mit Zusammenfassung gemergter PRs, geschlossener Tickets und Deployments)

• 5. Code Scaffolding & Templates

  • Skills, die Framework-Boilerplate für bestimmte Funktionen der Codebasis erzeugen
  • Sie lassen sich mit kombinierbaren Skripten verbinden und sind besonders nützlich, wenn es Anforderungen in natürlicher Sprache gibt, die sich nicht allein im Code abbilden lassen
  • Beispiele: new-framework-workflow(Scaffolding für neuen Service/Workflow/Handler mit Annotationen), new-migration(Vorlage für Migrationsdateien und Hinweise), create-app(neue interne App mit vorkonfigurierter Authentifizierung, Logging und Deployment-Einstellungen)

• 6. Code Quality & Review

  • Skills, die Codequalität in der Organisation durchsetzen und Code-Reviews unterstützen
  • Für maximale Robustheit können sie deterministische Skripte oder Tools enthalten
  • Sie können auch automatisch als Teil eines Hooks oder einer GitHub Action ausgeführt werden
  • Beispiele: adversarial-review(ein Subagent mit frischer Perspektive kritisiert → korrigiert → wiederholt, bis die Hinweise auf Nitpick-Niveau sinken), code-style(Durchsetzung eines Coding-Stils, den Claude standardmäßig nicht gut einhält), testing-practices(Hinweise zum Schreiben von Tests und dazu, was getestet werden soll)

• 7. CI/CD & Deployment

  • Skills, die Code innerhalb der Codebasis holen, pushen und deployen
  • Sie können zur Datensammlung auf andere Skills verweisen
  • Beispiele: babysit-pr(PR überwachen → flaky CI erneut ausführen → Merge-Konflikte lösen → Auto-Merge aktivieren), deploy-service(Build → Smoke-Tests → schrittweises Traffic-Rollout → Vergleich der Fehlerraten → automatisches Rollback bei Regression), cherry-pick-prod(isoliertes Worktree → Cherry-Pick → Konfliktlösung → PR aus Vorlage erzeugen)

• 8. Runbooks

  • Skills, die ein Symptom (Slack-Thread, Alarm, Error-Signatur usw.) als Eingabe nehmen, Untersuchungen mit mehreren Tools durchführen und einen strukturierten Bericht erstellen
  • Beispiele: service-debugging(Zuordnung Symptom → Tool → Abfragemuster), oncall-runner(Alarm abrufen → häufige Ursachen prüfen → Ergebnisse formatieren), log-correlator(Logs aller relevanten Systeme anhand einer Request-ID sammeln)

• 9. Infrastructure Operations

  • Skills, die tägliche Wartungs- und Betriebsverfahren ausführen und Guardrails für destruktive Aktionen enthalten
  • Sie erleichtern es Engineers, bei wichtigen operativen Aufgaben Best Practices einzuhalten
  • Beispiele: resource-orphans(verwaiste Pods/Volumes finden → Slack-Benachrichtigung → Wartezeit → Nutzerbestätigung → gestaffelte Bereinigung), dependency-management(organisatorischer Workflow zur Abnahme von Abhängigkeiten), cost-investigation(Buckets und Abfragemuster zur Untersuchung plötzlicher Spitzen bei Storage-/Egress-Kosten)

Tipps zum Schreiben von Skills

• Schreibe nichts Offensichtliches

  • Claude Code weiß bereits viel über die Codebasis und hat auch grundlegende Ansichten zum Programmieren
  • Wenn man einen wissenszentrierten Skill erstellt, sollte man sich auf Informationen konzentrieren, die Claude von seiner allgemeinen Denkweise abbringen
  • Der Skill frontend-design ist ein gutes Beispiel: Er wurde von Anthropic-Engineers durch wiederholte Arbeit mit Kund:innen erstellt, um Claudes Designgespür zu verbessern, und ist so aufgebaut, dass typische Muster wie die Inter-Schriftart und violette Farbverläufe vermieden werden

• Einen Gotchas-Abschnitt aufbauen

  • In allen Skills ist der inhaltlich wertvollste Teil der Gotchas-Abschnitt
  • Er sollte an den Fehlstellen, auf die Claude bei der Nutzung des Skills häufig stößt, angereichert werden
  • Idealerweise werden diese Gotchas im Lauf der Zeit kontinuierlich aktualisiert

• Dateisystem und Progressive Disclosure nutzen

  • Da Skills Ordner sind, sollte man das gesamte Dateisystem als Mittel für Context Engineering und Progressive Disclosure nutzen
  • Wenn man Claude mitteilt, welche Dateien im Skill vorhanden sind, liest es sie zum passenden Zeitpunkt
  • Die einfachste Form: Detaillierte Funktionssignaturen und Nutzungsbeispiele in ein separates Markdown wie references/api.md auslagern
  • Wenn die Endausgabe Markdown ist, kann man auch Template-Dateien im Ordner assets/ mitliefern
  • Ordner für Referenzen, Skripte und Beispiele erhöhen Claudes Arbeitseffizienz

• Claude nicht übermäßig einschränken

  • Claude versucht, Anweisungen zu befolgen, aber Skills sind stark wiederverwendbar, daher ist bei zu spezifischen Anweisungen Vorsicht geboten
  • Gib die nötigen Informationen, lasse aber Raum, sich flexibel an die Situation anzupassen

• Den Setup-Prozess entwerfen

  • Manche Skills brauchen eine Setup-Phase, in der Kontext vom Nutzer gesammelt wird
  • Beispiel: Wenn ein Skill ein Standup in Slack posten soll, muss er fragen, in welchen Channel gepostet werden soll
  • Ein gutes Muster: Setup-Informationen in einer config.json-Datei im Skill-Verzeichnis speichern; wenn noch nichts konfiguriert ist, fragt der Agent den Nutzer
  • Um strukturierte Multiple-Choice-Fragen zu stellen, kann man die Nutzung des Tools AskUserQuestion anweisen

• Das Description-Feld ist für das Modell

  • Wenn Claude Code eine Sitzung startet, erstellt es eine Liste der Description-Felder aller verfügbaren Skills
  • Diese Liste scannt Claude, um zu beurteilen: „Gibt es einen Skill, der zu dieser Anfrage passt?“
  • Daher ist das Description-Feld keine Zusammenfassung, sondern eine Erklärung, wann dieser Skill ausgelöst werden sollte

• Speicher und Datenspeicherung

  • Ein Skill kann Gedächtnis in Form gespeicherter Daten enthalten
  • Möglich sind einfache Text-Log-Dateien oder JSON-Dateien bis hin zu SQLite-Datenbanken
  • Beispiel: Wenn der Skill standup-post alle erstellten Einträge in standups.log speichert, kann Claude beim nächsten Lauf seine eigene Historie lesen und Änderungen seit gestern erkennen
  • Daten, die im Skill-Verzeichnis gespeichert werden, können bei Skill-Upgrades gelöscht werden; deshalb sollten sie in einem stabilen Ordner namens ${CLAUDE_PLUGIN_DATA} gespeichert werden

• Skripte speichern und Code generieren

  • Eines der mächtigsten Werkzeuge, die man Claude geben kann, ist der Code selbst
  • Wenn man Skripte und Bibliotheken bereitstellt, kann Claude sich statt auf das Rekonstruieren von Boilerplate auf Komposition konzentrieren
  • Beispiel: Ein Data-Science-Skill enthält eine Hilfsfunktionsbibliothek, die Daten aus Event-Quellen abruft
  • Claude kann diese Funktionen kombinieren und on the fly Skripte erzeugen, um komplexe Analysen wie „Was ist am Dienstag passiert?“ durchzuführen

• On Demand Hooks

  • Ein Skill kann Hooks enthalten, die nur beim Aufruf aktiviert werden und nur für die Dauer der Sitzung bestehen bleiben
  • Sie eignen sich für meinungsstarke Hooks, die zu aufwendig wären, um immer zu laufen, aber in bestimmten Situationen sehr nützlich sind
  • Beispiele:
    • /careful — blockiert rm -rf, DROP TABLE, force-push, kubectl delete mit einem PreToolUse-Matcher und wird nur bei Arbeiten in Produktion aktiviert
    • /freeze — blockiert alle Edit/Write außerhalb eines bestimmten Verzeichnisses; nützlich, um beim Debugging unbeabsichtigte Änderungen zu verhindern

Verteilung von Skills

• Einer der großen Vorteile von Skills ist, dass sie mit dem gesamten Team geteilt werden können
• Es gibt zwei Wege zum Teilen:
  • Skills ins Repository einchecken (unter ./.claude/skills)
  • Als Plugin erstellen und in den Claude Code Plugin-Marktplatz hochladen, damit Nutzer sie installieren können

• Verwaltung des Marktplatzes

  • Für kleine Teams, die in wenigen Repositories arbeiten, eignet sich das Einchecken ins Repository
  • Eingecheckte Skills werden dem Kontext des Modells nach und nach hinzugefügt; mit wachsender Größe ist daher ein interner Plugin-Marktplatz vorteilhaft
  • Es gibt kein zentrales Team, das entscheidet, welche Skills in den Marktplatz kommen; nützliche Skills werden auf natürliche Weise entdeckt
  • Wenn es einen Skill zum Ausprobieren gibt, lädt man ihn in den sandbox-Ordner auf GitHub hoch und weist etwa in Slack darauf hin
  • Sobald er genügend Traktion hat, erstellt der Skill-Eigentümer einen PR für die Verschiebung in den Marktplatz
  • Da sich leicht schlechte oder doppelte Skills erstellen lassen, ist vor dem Release ein Kurationsmechanismus wichtig

• Skills kombinieren (Composing Skills)

  • Zwischen Skills können Abhängigkeiten nötig sein (z. B. ein Datei-Upload-Skill plus ein Skill zum Erzeugen und Hochladen von CSVs)
  • Weder der Marktplatz noch Skills haben native eingebaute Abhängigkeitsverwaltung, aber wenn man andere Skills namentlich referenziert, ruft das Modell sie auf, sofern sie installiert sind

• Skills messen

  • Um die Wirksamkeit von Skills zu verstehen, wird die Skill-Nutzung im Unternehmen über PreToolUse-Hooks protokolliert
  • Das hilft, beliebte Skills oder auch Skills zu finden, die seltener als erwartet ausgelöst werden

Fazit

• Skills sind ein sehr mächtiges und flexibles Werkzeug für Agenten, befinden sich aber noch in einer frühen Phase, und alle sind noch dabei, den besten Einsatzweg zu finden
• Dieser Text ist kein endgültiger Leitfaden, sondern eine Sammlung von Tipps, die sich in der Praxis bewährt haben
• Die meisten Skills begannen mit ein paar Zeilen und einem Gotcha, und immer wenn Claude auf neue Randfälle stößt, fügen Menschen weiter hinzu und verbessern sie

[xguru]

Wenn ich Anthropic in letzter Zeit beobachte, habe ich den Eindruck, dass die für die Entwicklung Verantwortlichen ihre Erfahrungen so weit wie möglich teilen und die Leute dadurch dazu bringen, ihre Produkte besser zu nutzen.

Es wirkt wie ein Beispiel aus der Praxis dafür, wie man das Entwicklungsökosystem im Zeitalter der KI aufbaut.