KI-Agenten zur Automatisierung repetitiver Projektaufgaben einsetzen

Der schnellste Weg, einem KI-Agenten nicht immer wieder dasselbe Projekt erklären zu müssen, besteht darin, die Vorgehensweise einmalig als Claude Code Skill festzuhalten – ein Verzeichnis mit einer SKILL.md-Datei, das in das Repository eingecheckt wird und das der Agent liest, anstatt selbst herauszufinden, wie die App gestartet, mit Testdaten befüllt oder deployed werden soll.

Wer einmal dabei zugeschaut hat, wie ein Agent zehn Minuten damit verbringt, herauszufinden, dass die App ohne eine befüllte Datenbank und eine kopierte Env-Datei nicht startet, kennt das Gefühl. Genau diese Schritte wurden letzte Woche erklärt – und die Woche davor. Dieser Artikel zeigt das konkrete Muster: Wie sich ein Skill von einem npm-Skript unterscheidet, wo ein projektbezogener Skill abgelegt wird und ein funktionierendes Beispiel, das die App aus einem frischen Checkout heraus startet und verifiziert. Die These ist einfach: Schluss mit einmaligen Skripten, die in Vergessenheit geraten – stattdessen einen projektbezogenen Agenten-Skill entwickeln und einchecken, den das gesamte Team und der Agent gemeinsam nutzen.

Die eigentlichen Kosten vergesslicher npm-Skripte und veralteter Setup-Dokumentation

Das Teure an einem veralteten Setup-Prozess ist nicht der fehlerhafte Befehl selbst: Es ist die Tatsache, dass ein Mensch oder der Agent die Vorgehensweise jedes Mal neu herleiten muss. In einer package.json häufen sich kryptische Einträge an (predev:seed, db:reset:ci, start:tunnel), deren Reihenfolge und Vorbedingungen nur im Kopf einer einzigen Person existieren. Der Abschnitt „Getting Started” in der README verliert den Anschluss an die Realität, sobald jemand eine Umgebungsvariable hinzufügt und vergisst, sie zu dokumentieren. Neue Mitarbeitende raten; der KI-Agent rät ebenfalls – und beide kommen zu unterschiedlichen Schlüssen.

Ein Skill löst dieses Problem, indem er die Vorgehensweise dort festhält, wo der Agent ohnehin nachschlägt. Die offiziellen Claude Code-Dokumentation benennt den Auslöser für die Erstellung eines Skills präzise: Ein Skill sollte erstellt werden, wenn dieselben Anweisungen, Checklisten oder mehrstufigen Abläufe immer wieder in den Chat eingefügt werden, oder wenn ein Abschnitt der CLAUDE.md zu einem Ablaufbeschreibung angewachsen ist, anstatt eine bloße Tatsache festzuhalten.

Was ist der Unterschied zwischen einem Skript und einem Skill?

Skripte eignen sich für Schritte, die niemals variieren dürfen; Skills für Schritte, die Interpretation erfordern. Ein npm-Skript führt feste Befehle in einer vorgegebenen Reihenfolge aus; ein Skill nutzt das Modell, um Kontext zu lesen, mit Variabilität umzugehen und zu entscheiden, was als Nächstes zu tun ist – die deterministischen Teile werden dann wieder an Code übergeben. Beide ergänzen sich, sie konkurrieren nicht miteinander.

Das Engineering-Team von Anthropic plädiert dafür, deterministische Arbeit im Code zu belassen: Bestimmte Operationen sind für die traditionelle Codeausführung besser geeignet, denn eine Liste durch Token-Generierung zu sortieren ist langsamer und weniger zuverlässig als das Ausführen eines Sortieralgorithmus – und viele Workflows erfordern die Wiederholbarkeit, die nur Code bietet. Entscheidend ist dabei: Ein eingebettetes Skript bleibt kontexteffizient. Agenten mit Dateisystem- und Codeausführungs-Tools müssen nicht den gesamten Inhalt eines Skills in ihr Kontextfenster laden, was bedeutet, dass die Menge an Kontext, die in einem Skill gebündelt werden kann, praktisch unbegrenzt ist.

Was ist ein Claude Code Skill, und wo befindet er sich?

Ein Claude Code Skill ist ein Verzeichnis, das eine SKILL.md-Datei enthält, deren YAML-Frontmatter dem Agenten mitteilt, wann er ihn verwenden soll. Laut der Übersicht zu Agent Skills bündelt jeder Skill Anweisungen, Metadaten und optionale Ressourcen (Skripte, Templates), die Claude automatisch einsetzt, wenn sie relevant sind. Das ist das richtige mentale Modell: Ein Skill ist ein Verzeichnis, keine einzelne Befehlsdatei.

Der Ablageort bestimmt den Geltungsbereich. Projektbezogene Skills werden aus .claude/skills/ im Startverzeichnis und in übergeordneten Verzeichnissen bis zum Repository-Wurzelverzeichnis geladen, sodass ein Agent, der irgendwo innerhalb des Projekts arbeitet, den Skill als verfügbar erkennt und ihn automatisch lädt, wenn die Anfrage zu seiner Beschreibung passt. Persönliche Skills liegen unter ~/.claude/skills/. Für Claude Code speziell wird nur description empfohlen; name ist optional und entspricht standardmäßig dem Verzeichnisnamen, der auch nach / eingegeben wird.

Die Bausteine lassen sich leicht verwechseln, daher empfiehlt sich eine bewusste Entscheidung:

• Skill: Ein Verzeichnis + SKILL.md, optionale eingebettete Skripte. Wird über seine description automatisch erkannt und ist mit /skill-name aufrufbar. Funktioniert auch in Claude.ai und Claude Desktop, sodass ein Team ihn über das Terminal hinaus gemeinsam nutzen kann.
• Slash-Befehl: Historisch eine einzelne .md-Datei in .claude/commands/. Custom Commands wurden in Skills integriert: Eine Datei unter .claude/commands/deploy.md und ein Skill unter .claude/skills/deploy/SKILL.md erzeugen beide /deploy und verhalten sich identisch. Bei einem Namenskonflikt hat der Skill Vorrang.
• Subagent: Eine .md-Datei in .claude/agents/, die in einem eigenen Kontextfenster ausgeführt wird und ein komprimiertes Ergebnis zurückliefert. Empfehlenswert, wenn eine Aufgabe so leseintensiv ist, dass sie den Hauptthread belasten würde.

Praxisbeispiel: „App aus einem frischen Checkout starten und verifizieren” festhalten

Die eigene Setup-Routine in einen eingecheckten Skill umwandeln. Dazu .claude/skills/run-app/SKILL.md mit einer description erstellen, die spezifisch genug ist, damit der Agent sie zuordnen kann, mit vorangestellter Live-Befehlsausgabe und nummerierten Schritten:

---
name: run-app
description: Get this app running from a clean checkout and verify it boots. Use when setting up the project, onboarding, or checking the app still starts after a change.
allowed-tools: Bash(npm *) Bash(./scripts/verify.sh *)
---

## Environment
```!
node --version
npm --version
```

## Steps
1. Install dependencies with `npm ci`.
2. If `.env` is missing, copy `.env.example` to `.env`; ask before overwriting.
3. Start the app with `npm run dev`.
4. Run `./scripts/verify.sh` and report PASS or FAIL.

Expected output: a single PASS/FAIL line and the local URL the app serves on.

Der umzäunte ```!-Block nutzt dynamische Kontexteinbettung: Claude Code führt diese Befehle aus und fügt die Ausgabe ein, bevor der Agent den Skill liest – die Vorgehensweise erreicht den Agenten damit verankert in der tatsächlichen Toolchain, nicht als Vermutung. Mit der Anfrage „get the app running” lädt der Agent den Skill anhand seiner Beschreibung; /run-app eingeben, um ihn direkt aufzurufen.

Claude Code liefert dieses Muster auch als integrierten Skill mit. /run-skill-generator startet die App aus einer sauberen Umgebung heraus, hält fest, was funktioniert hat (die Installationsbefehle, die Umgebungsvariablen, das Startskript) und legt es als projektbezogenen Skill unter .claude/skills/run-<name>/ ab. Danach folgen /run, /verify und alle weiteren Agenten im Repository der dokumentierten Vorgehensweise, anstatt sie neu zu entdecken. /run, /verify und /run-skill-generator erfordern Claude Code v2.1.145 oder höher.

Skills zuverlässig machen und einchecken

Jeden Skill atomar halten und die erwartete Ausgabe explizit benennen: ein Skill, eine Aufgabe, ein klar definiertes Ergebnis, das in einem Pull Request überprüft werden kann. Vage Anweisungen führen zu Abweichungen; ein definiertes Ausgabeformat sorgt für konsistente Ausführungen und macht nachgelagerte Verarbeitung sicher.

Die unveränderlichen Schritte in ein eingebettetes scripts/verify.sh auslagern und den SKILL.md-Body die Interpretation übernehmen lassen: zu berichten, warum die Verifikation fehlgeschlagen ist, eine fehlende Umgebungsvariable zu erkennen. Diese Aufteilung macht den Workflow wiederholbar statt probabilistisch.

Eine echte Einschränkung sollte ehrlich benannt werden: Die automatische Aktivierung hängt vollständig von der description ab und greift nicht immer zuverlässig. Der erste Troubleshooting-Schritt in der Dokumentation ist zu prüfen, ob die Beschreibung Schlüsselwörter enthält, die Nutzende natürlicherweise verwenden würden. Wenn ein garantiert manueller Auslöser benötigt wird (bei allem mit Seiteneffekten), empfiehlt sich disable-model-invocation: true, damit der Skill nur bei Eingabe von /name ausgeführt wird.

Anschließend .claude/skills/ in die Versionskontrolle einchecken. Dieser eine Schritt schließt den Kreis: Die Vorgehensweise wird versioniert, überprüfbar und geteilt, sodass der nächste Mitarbeitende und die nächste Agentensitzung ein funktionierendes Verfahren erben, anstatt es rekonstruieren zu müssen. Skills sind in Claude.ai, Claude Code und der API verfügbar, und laut Anthropics Support-Dokumentation befinden sie sich auch für Claude Code-Nutzer sowie für alle API-Nutzer, die das Code-Execution-Tool verwenden, in der Beta-Phase. Ein eingecheckter Projektskill reist damit mit dem Repository mit, anstatt in der Shell-History einer einzelnen Person zu verweilen.

Am besten mit der am häufigsten wiederholten Aufgabe beginnen (der Clean-Checkout-Start, das Release-Changelog, das Seed-und-Reset): Die zugehörige SKILL.md schreiben, den deterministischen Teil als Skript bündeln und einchecken. Beim nächsten Mal, wenn jemand – oder der Agent – diese Vorgehensweise benötigt, ist sie bereits dokumentiert.

Häufig gestellte Fragen

Kann ich einen Claude Code Skill noch manuell aufrufen, oder wird er nur automatisch ausgelöst?

Beides ist möglich. Standardmäßig können sowohl Sie als auch Claude jeden Skill aufrufen: /skill-name eingeben, um ihn direkt auszuführen, und Claude kann ihn automatisch laden, wenn seine Beschreibung zur Anfrage passt. Ältere Anleitungen, die behaupten, Skills könnten nicht manuell ausgeführt werden, sind veraltet. Für rein manuelles Verhalten bei einem Skill mit Seiteneffekten disable-model-invocation auf true setzen, sodass er nur bei Eingabe seines Namens ausgeführt wird.

Was passiert, wenn ein Slash-Befehl und ein Skill denselben Namen haben?

Der Skill hat Vorrang. Custom Commands wurden in Skills integriert: Eine Datei unter .claude/commands/deploy.md und ein Skill unter .claude/skills/deploy/SKILL.md erzeugen beide denselben /deploy-Befehl und verhalten sich identisch. Existieren beide unter demselben Namen, lädt Claude Code den Skill anstelle der Befehlsdatei – es ist daher nicht notwendig, für einen Befehl beides zu pflegen.

Verbraucht ein eingebettetes Skript innerhalb eines Skills Kontextfenster-Tokens?

Nein. Wenn die Anweisungen eines Skills auf ein ausführbares Skript verweisen, führt Claude es per Bash aus und erhält nur die Ausgabe; der Skriptcode selbst gelangt nie in das Kontextfenster. Deshalb ist es kostengünstiger und zuverlässiger, deterministische Arbeit als Skript zu bündeln, als das Modell darum zu bitten, sie zu durchdenken – und deshalb sind die Ressourcen, die ein Skill bündeln kann, in ihrer Größe praktisch unbegrenzt.

Muss ich einen kostenpflichtigen Plan abonnieren, um Claude Code Skills zu nutzen?

Nein. Laut Anthropics Support-Dokumentation sind Skills in den Plänen Free, Pro, Max, Team und Enterprise verfügbar, und die Funktion erfordert, dass die Codeausführung aktiviert ist. In Claude Code speziell befinden sich Skills in der Beta-Phase; sie funktionieren auch für alle API-Nutzer, die das Code-Execution-Tool verwenden. Da sich Verfügbarkeitsdetails häufig ändern, empfiehlt sich ein Abgleich mit der aktuellen Support-Dokumentation von Anthropic.