Claude Code Skills: zwei, die laufen, und einer, der gestorben ist

Ich baue einen Skill nur, wenn er einen Mehrwert verspricht, und das ist bei komplexeren Abläufen der Fall. Der Weg dahin ist immer derselbe: Ich gehe den kompletten Prozess einmal mit der KI durch. Erst wenn dieser Durchlauf sauber funktioniert hat, lasse ich daraus einen Skill erzeugen.

Der Skill ist damit nicht der Anfang, sondern das Ergebnis. Er hält einen Weg fest, der vorher nachweislich funktioniert hat, statt einen zu beschreiben, von dem ich glaube, dass er funktionieren müsste.

Und die Gegenprobe: Wenn sich eine Aufgabe nicht wiederholt, brauche ich keinen Skill. Wiederholung ist die Bedingung, nicht Schwierigkeit.

Bei mir ist das ein Skill, der eine read-only CLI bedient. Das Tool selbst habe ich mir von Claude Code entwickeln lassen; es fragt die REST-API unseres Fachsystems ab und kann ausschließlich lesen. Der Skill ist die Bedienungsanleitung dazu: Er sagt Claude, welche Befehle es gibt, welche Regeln gelten und was man nicht tun soll.

Ich nutze ihn mehrfach pro Woche. Täglich wäre übertrieben.

Der typische Fall: eine Bestellung, die nicht durchläuft

Die häufigste Frage, die bei mir landet, lautet: Warum wurde diese Bestellung nicht abgeschlossen? Ich habe eine Bestellnummer, und damit schicke ich die Recherche los. Die CLI gibt unter anderem den Verlauf der Bestellung aus, und der beantwortet die Frage in vielen Fällen bereits allein.

Für diese Klasse von Fragen hat der Skill mein manuelles SQL vollständig ersetzt. Bei komplexeren Fällen übernimmt er nur die Ersteinschätzung und einen Abgleich mit dem Code, ob es dort Auffälligkeiten gibt. Den Rest mache ich weiter selbst.

Der eigentliche Hebel: Daten und Code in einem Schritt

Das Praktische ist nicht, dass ein Tool bedient wird. Das Praktische ist, dass Claude die Bestellung aus der API und den Code, der sie verarbeitet, gleichzeitig ansieht.

Ein Support-Backend zeigt mir nur die Daten. Ein Debugger zeigt mir nur den Code. Die Frage, warum ausgerechnet dieser Datensatz in diesem Zustand hängen bleibt, liegt aber genau dazwischen. Genau diese Lücke schließt der Skill, und das ist der Grund, warum er nicht wieder aus meinem Alltag verschwunden ist.

Vorher: SQL von Hand

Vor dem Tool habe ich diese Recherche manuell in der Datenbank gemacht, mit eigenen SQL-Befehlen. Das war gründlich, aber langsam: Für so einen Fall sind gut mal 30 Minuten draufgegangen.

Heute ist es etwas schneller. Genauer kann ich es nicht sagen, und ich will hier auch keine Prozentzahl erfinden, der Unterschied liegt weniger in den Minuten als darin, dass ich die Recherche nicht mehr selbst führen muss. Der Skill ist schneller und flacher, und für einen ersten Überblick ist flach völlig ausreichend.

Der zweite, den ich sehr regelmäßig nutze, erzeugt GitHub-Issues in einer vorgegebenen Struktur. Der Zweck ist unspektakulär: Jedes Issue hat denselben Aufbau, egal wann und in welchem Zustand ich es anlege.

Entstanden ist er wie beschrieben, wir haben einen gemeinsamen Durchlauf gemacht, und aus dem hat die KI den Skill erzeugt. Kein vorher hingeschriebenes Konzept.

Der eigentliche Wert liegt im Zeitpunkt der Nutzung. Wenn ich mit Claude Code an Code sitze und uns fällt etwas auf, legen wir das Issue direkt gemeinsam an, um später darauf zurückzukommen. Ich muss die Sitzung dafür nicht verlassen, und der Gedanke geht nicht verloren, während ich am eigentlichen Problem weiterarbeite.

Das ist ein anderer Nutzen als beim ersten Beispiel. Dort geht es um Zugriff auf ein System. Hier geht es um Form und um den Moment: Ein Skill kann auch einfach dafür sorgen, dass etwas überhaupt festgehalten wird.

Es gab bisher keinen Fall, in dem der Skill mich in die falsche Richtung geschickt hätte. Es gab aber Fälle, in denen die Datenabfrage nichts Entscheidendes beigetragen hat. Dann haben wir die Fehlersuche direkt im Code gemacht, ohne vorher überhaupt Daten abzurufen.

Der Grund ist strukturell: Das Tool liefert über die API weniger, als ich als Entwickler direkt in der Datenbank sehe. Ein Skill, der eine API kapselt, ist immer nur so gut wie die API-Oberfläche. Wo ich vollen Datenbankzugriff habe, ist er ein Umweg.

Dazu kommt der Datenschutz. Wichtige Daten geben wir nicht außer Haus, deshalb ist die Suche auf dem Produktivsystem nicht immer komplett treffsicher. Sie reicht zum Einkreisen, nicht zum Beweis.

Auf dem lokalen System und auf dem Testsystem fällt diese Bremse weg, weil dort mit Testdaten gearbeitet wird. Dort ist der Skill deutlich mehr als ein Support-Werkzeug, er hilft im normalen Entwickleralltag.

Das Original bedient ein internes System, deshalb steht hier eine anonymisierte Fassung: andere Namen, ein reduzierter Befehlssatz, keine echten Entitäten. Das Muster ist dasselbe, und genau darum geht es: eine read-only CLI, ein Pflicht-Flag für die Umgebung, explizite Anti-Patterns und eine Liste der Fehlermeldungen, die im Betrieb wirklich auftreten.

---
name: api-inspect
description: Read-only CLI zum Inspizieren unseres Fachsystems über dessen REST-API. Nutze diesen Skill, wenn Daten aus dem System nachgesehen werden sollen: Bestellungen, Kunden, Rechnungen, Zahlungen. Trigger bei Anfragen wie "warum wurde Bestellung X nicht abgeschlossen", "wer ist Kunde Y", "zeig mir die Rechnung", "warum stockt der Checkout". Nicht verwenden für Änderungen, das Tool ist read-only.
---

# api-inspect

CLI zum Inspizieren unseres Fachsystems. Read-only, damit gegenüber
Produktivdaten unkritisch.

## Aufruf

Das Tool ist global installiert und wird immer als `api-inspect`
aufgerufen, nie über `node`, `npx` oder relative Pfade:

```bash
api-inspect <befehl> [<args>] --profile=<name> [--json] [--limit=<n>]
```

`--profile` ist Pflicht. Verfügbare Profile listen:

```bash
api-inspect profiles
```

## Wichtige Regeln

1. Niemals raten, welches Profil gilt. Wenn unklar, den Nutzer fragen.
   `prod` nur, wenn er das ausdrücklich sagt.
2. `--json` nur, wenn die Daten weiterverarbeitet werden. Für Menschen
   ist die Standardausgabe gedacht.
3. Read-only: Es gibt keinen Schreibbefehl. Wer etwas ändern will, muss
   ins Backend-UI.
4. Einzelne Endpoints dürfen 401 oder 404 liefern, das ist normal. Bei
   `--json` sieht man den Rohzustand.
5. Vor dem Vorschlagen eines Befehls darf er kurz mit harmlosen IDs gegen
   `--profile=local` ausprobiert werden, statt zu raten.

## Befehle

| Befehl | Zweck |
|---|---|
| `api-inspect order <id>` | Bestellung komplett, inklusive Verlauf |
| `api-inspect customer <id>` | Kunde mit Stammdaten und letzten Bestellungen |
| `api-inspect invoice <id>` | Rechnung inklusive Erstattungen |
| `api-inspect payment <order-id>` | Zahlungsvorgänge einer Bestellung |
| `api-inspect cart <id>` | Warenkorb, für Checkout-Diagnose |
| `api-inspect orders [--limit=N]` | Letzte Bestellungen |
| `api-inspect search "<term>"` | Globale Suche, bester Einstieg bei unklarem Anliegen |
| `api-inspect profiles` | Verfügbare Profile |

## Globale Optionen

| Flag | Bedeutung |
|---|---|
| `--profile=<name>` | Umgebung: `local`, `test` oder `prod` (Pflicht) |
| `--json` | Maschinenlesbare Ausgabe |
| `--limit=<n>` | Anzahl Einträge bei Listen |
| `--verbose` | Debug-Logging |

## Muster

### "Warum wurde Bestellung X nicht abgeschlossen?"

```bash
api-inspect order 12345 --profile=prod
```

Der Verlauf in der Ausgabe beantwortet die Frage meistens allein. Wenn
ein Zahlungsproblem vermutet wird:

```bash
api-inspect payment 12345 --profile=prod
```

### Unklare Identifikation

```bash
api-inspect search "Mustermann" --profile=prod
api-inspect customer 99 --profile=prod
```

## Anti-Patterns

- Das Tool über `node dist/index.js` oder `npx` aufrufen. Es ist global.
- Ohne `--profile` aufrufen. Bricht mit Fehlermeldung ab.
- Rohe API-Calls per `curl` zusammenbauen, wenn es einen Befehl gibt.
- `--json` parsen, wenn die normale Ausgabe reicht.
- Bei 404 aufgeben. Meistens hilft `search` oder ein anderer Identifier.

## Fehlerfälle

- `Cannot connect to profile` → Profildaten falsch oder Server nicht
  erreichbar. `api-inspect profiles` prüfen.
- `Profile '...' not found` → fehlt in der Config.
- `... nicht gefunden` → Endpoint hat 404 geliefert. ID prüfen, sonst
  `search`.
- `Error: --profile is required` → Flag vergessen.

Der Teil, der in meiner ersten Fassung fehlte und den ich für den wichtigsten halte, ist die description im Frontmatter. Sie entscheidet, ob der Skill überhaupt gezogen wird. Warum das so wichtig ist, zeigt weiter unten das Gegenbeispiel.

Mein erster eigener Skill sollte Fehlermeldungen einschätzen: Stacktrace einlesen, betroffene Module zuordnen, Ursachenhypothesen mit Belegen ausgeben. Die Idee war, dass die KI Fehler damit besser analysiert. Ich benutze ihn nicht mehr.

Gestorben ist er in zwei Schritten. Zuerst hat Claude ihn nicht zuverlässig gezogen, ich musste ihn praktisch von Hand anstoßen. Danach ist die Aufgabe ganz woanders hingewandert: Ich weise Claude heute eine bereits anonymisierte Fehlermeldung zu, und es sucht im Code nach möglichen Erklärungen. Das läuft auf einem anderen Rechner. Damit war der Skill überflüssig, noch bevor ich ihn reparieren konnte.

Warum er nicht gezogen wurde, weiß ich nicht mit Sicherheit. Meine Vermutung ist, dass er zu wenig auf uns zugeschnitten war. Ich hätte mehr Zeit in die Verbesserung stecken sollen und habe es am Ende nicht getan.

Im Rückblick würde ich zuerst an der description ansetzen, nicht am Inhalt: Sie ist der Teil, der über das Ziehen entscheidet, und in meiner Fassung war sie zu allgemein. Ein einmaliges „nutze diesen Skill" hilft übrigens nicht dauerhaft, das gilt nur für die laufende Sitzung. Wer will, dass ein Skill verlässlich greift, schreibt entweder eine präzisere description oder eine Zeile in die CLAUDE.md.

Es liegt nahe, den Unterschied in der Schwierigkeit zu suchen. Fehleranalyse ist anspruchsvoller als das Abfragen einer Bestellung, also hätte man erwarten können, dass genau dort ein Skill am meisten hilft. Das Gegenteil ist eingetreten.

Der Unterschied liegt in der Wiederholbarkeit. Fehleranalyse ist kein wiederholbarer Ablauf: Jeder Fehler ist anders, der Denkweg jedes Mal neu. Damit verstößt so ein Skill gegen die Regel, nach der ich sonst vorgehe, Skill nur bei Wiederholung. Die CLI-Bedienung dagegen kapselt einen festen Satz Befehle mit festen Regeln. Sie ist maximal wiederholbar, und deshalb läuft sie.

Ein Skill kodifiziert einen Weg. Wo es keinen festen Weg gibt, gibt es auch nichts zu kodifizieren.

Drei Dinge, die ich heute anders mache als bei meinem ersten Skill:

• Den Skill nicht vorher schreiben, sondern aus einem Durchlauf ableiten, der schon funktioniert hat.
• Vor dem Bauen prüfen, ob die Aufgabe wirklich wiederkehrt. Wenn nicht, ist ein Prompt die richtige Antwort und kein Skill.
• Die description so schreiben, dass klar ist, wann der Skill greifen soll. Der beste Inhalt ist wertlos, wenn er nie gezogen wird.

Wie sich diese Arbeitsweise im Vergleich zu OpenCode verhält, steht auf der Seite zu OpenCode und Claude Code im Parallelbetrieb. Und wenn ein Werkzeug statt eines Skills die richtige Antwort ist, führt der Weg meist zu einem MCP-Server.