Agent Skills Guide
Ein Agent Skill ist ein wiederverwendbares Instruktionspaket, das einem AI-Agenten beibringt, wie er eine wiederkehrende Art von Arbeit erledigt. Statt dieselbe Checkliste, Prozedur oder dasselbe Playbook immer wieder in den Chat zu kopieren, speicherst du sie einmal als SKILL.md-basierte Fähigkeit und lässt den Agenten sie laden, wenn sie relevant ist.
Dieser Guide basiert primär auf der offenen Agent Skills-Spezifikation unter agentskills.io und der aktuellen Claude Code skills-Dokumentation. Der offene Standard definiert das portable Skill-Format; Claude Code erweitert es um produktspezifische Features wie Invocation Control, Subagent-Ausführung und dynamische Kontext-Injektion.
1. Was ein Skill ist​
Ein Skill versteht man am besten als ein kleines Fähigkeitspaket:
- eine
SKILL.md-Datei mit Metadaten und Instruktionen, - optionale
scripts/, die der Agent ausfĂĽhren kann, - optionale
references/, die der Agent bei Bedarf lesen kann, - optionale
assets/wie Vorlagen oder Schemas.
Typische Beispiele:
- eine Release-Checkliste,
- eine Code-Review-Prozedur,
- ein Debugging-Workflow,
- ein Deployment-Rezept,
- ein projektspezifischer "So fĂĽhrst du diese App aus"-Leitfaden,
- ein Hausstil fĂĽr Architektur-Doku oder API-Design.
Die Kernidee ist einfach:
- Prompts sind einmalig,
- Skills sind wiederverwendbar.
2. Skill vs. Prompt vs. Tool vs. MCP​
Diese Konzepte sind verwandt, aber nicht dasselbe.
| Konzept | Was es ist | Am besten fĂĽr |
|---|---|---|
| Prompt | Eine Instruktion in einer Konversation | Einmalige Anfragen |
| Skill | Wiederverwendbare Instruktionen plus optionale Dateien und Skripte | Wiederholbare Workflows |
| Tool | Eine aufrufbare Funktion oder Fähigkeit | Eine einzelne konkrete Aktion |
| MCP-Server | Eine protokollbasierte Integration, die Tools, Prompts oder Ressourcen bereitstellt | Externe Systeme und strukturierter Zugriff |
Projektgedächtnis (CLAUDE.md, Repo-Doku usw.) | Dauerhafter Kontext zu einem Repo oder einer Organisation | Fakten, Konventionen, Einschränkungen |
Gute Faustregel:
- wenn der Agent eine Aktion braucht, nutze ein Tool;
- wenn der Agent eine Prozedur braucht, nutze einen Skill;
- wenn der Agent Hintergrundfakten braucht, nutze Projektgedächtnis oder Doku.
3. Warum Skills wichtig sind​
Ohne Skills neigen Agents dazu, generischen Output zu produzieren:
- durchschnittlich aussehende Frontend-Arbeit,
- oberflächliche Reviews,
- inkonsistente Rollout-Schritte,
- immer wieder neu entdeckte Setup-Anweisungen,
- fragile mehrstufige Workflows.
Mit Skills verschiebst du die Defaults.
Das ist der eigentliche Wert: nicht "das Modell kann technisch mehr", sondern "das Modell leistet die richtige Art von Arbeit konsistenter."
Skills sind besonders nĂĽtzlich, wenn:
- du dieselben Instruktionen immer wieder wiederholst,
- eine Prozedur ĂĽber mehrere Schritte reicht,
- die Qualität von einer Checkliste abhängt,
- die Arbeit projektspezifischen Kontext braucht,
- du dasselbe Verhalten im gesamten Team willst.
4. Wie Skills funktionieren​
Das aktuelle Skill-Modell nutzt Progressive Disclosure.
Auf hoher Ebene:
- der Agent weiĂź aus den Metadaten, dass der Skill existiert,
- er lädt den vollständigen
SKILL.md-Body, wenn die Aufgabe relevant aussieht, - er lädt Skripte, References und Assets nur, wenn sie gebraucht werden.
Das ist wichtig, weil lange Instruktionen nicht mehr von Anfang an in jedem Chat sitzen mĂĽssen.
Der Skill-Body und die unterstützenden Dateien kosten fast nichts, bis der Skill tatsächlich genutzt wird. Das macht Skills zu einem besseren Ort für Prozeduren, References und Playbooks, als alles in dauerhaft aktiven Kontext zu stopfen.
In Tools wie Claude Code können Skills auf zwei Arten genutzt werden:
- automatisch, wenn die Beschreibung zur Aufgabe passt,
- manuell, indem du den Skill direkt aufrufst, zum Beispiel mit
/skill-name.
5. Wo Skills liegen​
Die genauen Speicherorte hängen vom Client ab, aber das allgemeine Muster ist:
| Geltungsbereich | Typischer Ort | FĂĽr wen er gilt |
|---|---|---|
| Persönlich | ~/.claude/skills/<skill-name>/SKILL.md | Deine eigene Arbeit über Projekte hinweg |
| Projekt | .claude/skills/<skill-name>/SKILL.md | Ein Repository oder Workspace |
| Enterprise / verwaltet | zentral konfiguriert | Eine Organisation |
| Plugin-bereitgestellt | innerhalb eines Plugin-Bundles | Wo immer dieses Plugin aktiviert ist |
Praktische Hinweise:
- lege persönliche Arbeitsgewohnheiten in persönliche Skills,
- lege repo-spezifische Workflows in Projekt-Skills,
- lege gesteuerte Team-Standards in enterprise-verwaltete Skills.
6. Was ein Skill üblicherweise enthält​
Der offene Standard ist bewusst einfach.
Erforderliches Minimum​
Ein Skill-Verzeichnis braucht mindestens:
skill-name/
└── SKILL.md
Häufige vollständige Form​
skill-name/
├── SKILL.md
├── scripts/
├── references/
└── assets/
SKILL.md​
Die SKILL.md-Datei enthält:
- Frontmatter-Metadaten wie
nameunddescription, - die tatsächlichen Instruktionen, denen der Agent folgen soll.
scripts/​
Nutze Skripte, wenn der Skill ausfĂĽhrbare Hilfe braucht, zum Beispiel um:
- Daten zu sammeln,
- Output zu validieren,
- Checks auszufĂĽhren,
- Dateien zu transformieren,
- zu vermeiden, dass das Modell fragile Logik von Grund auf neu erstellen muss.
references/​
Nutze References fĂĽr:
- lange Prozeduren,
- domänenspezifische Notizen,
- API-Details,
- Beispiele, die nur bei Bedarf laden sollen.
assets/​
Nutze Assets fĂĽr:
- Vorlagen,
- Schemas,
- statische Beispiele,
- Nachschlagedateien.
7. Wann man einen Skill erstellt​
Erstelle einen Skill, wenn die Arbeit wiederholbar genug ist, um einen benannten Workflow zu verdienen.
Starke Kandidaten:
- Code-Review
- Deployment
- Release Notes
- Meeting-Vorbereitung
- Umgebungs-Setup
- Architecture Decision Records
- Teststrategie
- Incident-Response-Checklisten
- "fĂĽhre dieses Projekt lokal aus"-Rezepte
Schwache Kandidaten:
- eine einmalige Antwort,
- generisches Wissen, das das Modell bereits kennt,
- eine winzige Instruktion, die leichter direkt zu sagen als als Skill zu pflegen ist.
Wenn du in etwa dieselben Instruktionen schon zwei- oder dreimal kopiert hast, ist das oft Beleg genug, dass ein Skill existieren sollte.
8. Was einen guten Skill ausmacht​
Ein guter Skill ist:
- auffindbar: die Beschreibung sagt klar, was er tut und wann man ihn nutzt,
- abgegrenzt: er deckt eine Aufgabe gut ab statt fĂĽnf Aufgaben schlecht,
- praktisch: er hilft dem Agenten, echte Arbeit zu erledigen, nicht nur darĂĽber zu reden,
- leichtgewichtig: die Hauptdatei bleibt prägnant und schiebt Details bei Bedarf in References,
- dort meinungsstark, wo es zählt: er lehrt Defaults, Checklisten und Qualitätsmaßstäbe.
Häufige Fehler:
- vage Beschreibungen wie "hilft beim Coding",
- ĂĽbergroĂźe
SKILL.md-Dateien, die aufgeteilt werden sollten, - Fakten, Richtlinien und Prozeduren in einen Klumpen zu mischen,
- einen Skill fĂĽr etwas zu erstellen, das einfach ein Tool sein sollte,
- Regeln zu schreiben, ohne zu erklären, warum sie wichtig sind.
9. Typische Beispiele​
Hier sind einige realistische Beispiele dafĂĽr, was ein Skill leisten kann:
| Skill-Idee | Was er dem Agenten beibringt |
|---|---|
| Code-Review | Auf Regressionen, Risiken, fehlende Tests, toten Code und unsichere Ă„nderungen achten |
| App ausfĂĽhren / verifizieren | Das Projekt korrekt starten, inklusive Umgebungsvariablen, Diensten und Startschritten |
| API-Design | Deine Ressourcen-Konventionen, Benennungsregeln und Response-Muster anwenden |
| Security-Review | Auth-Grenzen, Secrets, Injection-Risiken und unsichere Defaults prĂĽfen |
| Doku-Publishing | Doku im Hausstil schreiben und Links vor dem Ausliefern validieren |
Deshalb stehen Skills zwischen "bloĂźem Prompting" und "voller Integration". Sie kodieren Arbeitsmethode.
10. Entscheidungshilfe​
| Wenn du … willst | Tu das … |
|---|---|
| einen Workflow wiederverwenden, den du immer wiederholst | einen Skill erstellen oder installieren |
| dem Agenten eine konkrete Fähigkeit geben | ein Tool hinzufügen oder nutzen |
| dauerhafte Repo-Konventionen speichern | Projekt-Doku oder CLAUDE.md-artiges Gedächtnis nutzen |
| einen komplexen Prozess mit Beispielen und Dateien lehren | einen Skill mit references/ und scripts/ nutzen |
| einen Agenten teamweit besser arbeiten lassen | Projekt- oder Enterprise-Skills teilen |
11. Wohin als Nächstes​
- Must-Have Skills – kuratierte Beispiele für hochwertige Skills, die du zuerst installieren solltest
- Skill Authoring – wie man eine
SKILL.mdgut entwirft und schreibt
Wenn das Konzept neu fĂĽr dich ist, lies zuerst diese Seite. Wenn du bereits weiĂźt, dass du Skills erstellen oder verbessern willst, springe direkt zu Skill Authoring.