Benutzerdefinierte Claude Code Skills erstellen

Was sind Skills?

Claude Code Skills sind verpackte Fähigkeiten, die erweitern, was Claude Code tun kann. Ein Skill nimmt einen komplexen, mehrstufigen Workflow und kodiert ihn in einen wiederverwendbaren Befehl, den jedes Teammitglied aufrufen kann.

Betrachten Sie dieses Szenario: Jedes Mal, wenn ein Entwickler einen neuen API-Endpunkt erstellt, muss er:

Den Route-Handler mit korrekter Fehlerbehandlung generieren
TypeScript-Typen für Request/Response erstellen
Eingabevalidierung hinzufügen
Unit-Tests schreiben
API-Dokumentation generieren
Die OpenAPI-Spezifikation aktualisieren

Ohne Skill geht jeder Entwickler dies anders an. Einige überspringen Schritte. Einige machen sie in unterschiedlicher Reihenfolge. Die Qualität variiert stark.

Mit einem Skill ruft er /create-api-endpoint auf und erhält jedes Mal konsistente, vollständige Outputs. Der Skill kodiert die Best Practices Ihres Teams und erzwingt sie automatisch.

Skills vs. Prompts vs. Workflows

Das Verständnis der Unterscheidung hilft Ihnen, das richtige Tool zu wählen:

Prompts sind einzelne Anweisungen. Sie sagen Claude, was in einer Interaktion zu tun ist.

Prüfe diesen Code auf Sicherheitslücken.

Templates sind strukturierte Prompts mit Platzhaltern. Sie standardisieren, wie Prompts geschrieben werden.

Prüfe [CODE] auf [KATEGORIE]-Probleme gemäß [STANDARDS].

Skills sind vollständige Workflows, die mehrere Interaktionen umfassen können, Tool-Aufrufe beinhalten, auf externe Systeme zugreifen und komplexe Outputs produzieren.

/security-audit
→ Liest Codebase-Struktur
→ Identifiziert sicherheitsrelevante Dateien
→ Analysiert jede auf Schwachstellen
→ Vergleicht gegen OWASP-Richtlinien
→ Generiert priorisierten Bericht mit Fixes

Workflows orchestrieren mehrere Skills zu größeren Prozessen.

/release-prep
→ Führt /changelog-generator aus
→ Führt /security-audit aus
→ Führt /dependency-check aus
→ Führt /documentation-update aus
→ Produziert Release-Bereitschaftsbericht

Der Skill-Entwicklungszyklus

Der Aufbau produktionsreifer Skills folgt einem strukturierten Prozess. Schritte zu überspringen führt zu Skills, die in Demos funktionieren, aber in der realen Nutzung scheitern.

Phase 1: Ideenfindung und Validierung

Nicht jeder Workflow sollte zu einem Skill werden. Gute Skill-Kandidaten haben diese Eigenschaften:

Hohe Frequenz: Workflows, die täglich oder wöchentlich im Team stattfinden

API-Endpunkt-Erstellung
Code-Review-Unterstützung
Dokumentationsgenerierung
Test-Scaffolding

Hoher Wert: Workflows, bei denen Konsistenz signifikant wichtig ist

Sicherheitsaudits
Compliance-Checks
Release-Vorbereitung
Incident Response

Hohe Komplexität: Workflows mit vielen Schritten, die leicht falsch gemacht werden können

Datenbank-Migrationen
Dependency-Upgrades
Refactoring-Kampagnen
System-Integrationen

Validierungsfragen:

Wie oft passiert dieser Workflow? (Täglich = hohe Priorität)
Was kostet es, ihn inkonsistent zu machen? (Sicherheit = hohe Kosten)
Wie viel Zeit braucht er aktuell? (>30 Min = guter Kandidat)
Kann er vernünftig automatisiert werden? (Manche Aufgaben brauchen menschliches Urteil)

Phase 2: Design und Prototyping

Vor dem Schreiben des Skills, designen Sie sein Interface und Verhalten.

Eingabe-Design: Welche Informationen braucht der Skill?

skill: create-api-endpoint
inputs:
  required:
    - name: endpoint_path
      type: string
      description: "API-Pfad (z.B. /users/:id)"
    - name: method
      type: enum[GET, POST, PUT, DELETE, PATCH]
      description: "HTTP-Methode"
  optional:
    - name: auth_required
      type: boolean
      default: true
      description: "Ob Authentifizierung erforderlich ist"
    - name: rate_limit
      type: number
      default: 100
      description: "Anfragen pro Minute Limit"

Output-Design: Was produziert der Skill?

outputs:
  files:
    - path: "src/routes/{endpoint}.ts"
      type: "route_handler"
    - path: "src/types/{endpoint}.ts"
      type: "typescript_types"
    - path: "tests/{endpoint}.test.ts"
      type: "unit_tests"
    - path: "docs/api/{endpoint}.md"
      type: "documentation"
  updates:
    - path: "openapi.yaml"
      section: "paths"

Fehlerbehandlungs-Design: Was kann schiefgehen?

error_conditions:
  - condition: "endpoint_already_exists"
    message: "Endpunkt {path} existiert bereits. Nutze /update-endpoint stattdessen."
    recovery: "suggest_alternative"

  - condition: "invalid_path_format"
    message: "Pfad muss mit / beginnen und :param für Parameter verwenden"
    recovery: "prompt_for_correction"

  - condition: "missing_dependencies"
    message: "Erforderliches Paket {package} nicht in package.json gefunden"
    recovery: "offer_to_install"

Prototyp: Erstelle eine minimale Version zur Validierung des Ansatzes.

# create-api-endpoint (v0.1 Prototyp)

## Trigger
Benutzer ruft auf: /create-api-endpoint [pfad] [methode]

## Schritte
1. Eingaben parsen und Format validieren
2. Prüfen ob Endpunkt existiert
3. Route-Handler aus Template generieren
4. Typen aus Handler generieren
5. Grundlegende Test-Datei generieren
6. Zusammenfassung ausgeben

## Notizen für v1.0
- OpenAPI-Integration hinzufügen
- Vollständige Validierungslogik-Generierung hinzufügen
- Rate-Limiting-Setup hinzufügen

Phase 3: Implementierung

Mit validiertem Design, implementiere den vollständigen Skill.

Skill-Datei-Struktur:

---
name: create-api-endpoint
version: 1.0.0
description: Erstellt einen vollständigen API-Endpunkt mit Typen, Tests und Docs
author: platform-team
tags: [api, scaffolding, typescript]
---

# API-Endpunkt erstellen

## Trigger-Bedingungen
Dieser Skill aktiviert sich wenn:
- Benutzer `/create-api-endpoint` aufruft
- Benutzer fragt "erstelle einen neuen API-Endpunkt"
- Benutzer fragt "füge einen Endpunkt für [Ressource] hinzu"

## Eingabebehandlung

### Erforderliche Eingaben
Vom Benutzer erfragen, wenn nicht angegeben:
- **endpoint_path**: Der API-Pfad (z.B. `/users/:id`)
- **http_method**: GET, POST, PUT, DELETE oder PATCH

### Optionale Eingaben
Defaults verwenden, wenn nicht angegeben:
- **auth_required**: true
- **rate_limit**: 100 Anfragen/Minute
- **response_type**: json

### Validierungsregeln
- Pfad muss mit `/` beginnen
- Pfad-Parameter verwenden `:paramName` Format
- Methode muss gültige HTTP-Methode sein

## Ausführungsschritte

### Schritt 1: Kontext sammeln
<tool>read_file</tool>
- `src/routes/index.ts` lesen um Routing-Muster zu verstehen
- `src/middleware/auth.ts` lesen für Auth-Setup
- Bestehenden Endpunkt lesen für Muster-Matching

### Schritt 2: Route-Handler generieren
Erstelle `src/routes/{resource}.ts`:
```typescript
// Template mit Team-Mustern:
// - Fehlerbehandlung mit custom ApiError
// - Request-Validierung mit zod
// - Response-Typisierung
// - Logging-Integration

Schritt 3: Typen generieren

Erstelle src/types/{resource}.ts:

// Request- und Response-Typen
// Zod-Schemas für Validierung
// Export für Nutzung in Tests

Schritt 4: Tests generieren

Erstelle tests/routes/{resource}.test.ts:

// Test-Struktur passend zu Team-Mustern
// Happy-Path-Tests
// Fehlerfall-Tests
// Auth-Tests wenn auth_required

Schritt 5: OpenAPI aktualisieren

Modifiziere openapi.yaml:

Pfad-Definition hinzufügen
Request/Response-Schemas hinzufügen
Authentifizierungsanforderungen hinzufügen

Schritt 6: Zusammenfassungs-Output

Bereitstellen:

Liste erstellter/modifizierter Dateien
Nächste Schritte für den Entwickler
Etwaige manuelle Schritte erforderlich

Fehlerwiederherstellung

Endpunkt existiert

Wenn Endpunkt bereits existiert:

Bestehende Implementierung zeigen
Update stattdessen anbieten
Erstellung mit anderem Pfad anbieten

Validierung fehlgeschlagen

Wenn Eingaben nicht validieren:

Erklären was falsch ist
Korrektes Format zeigen
Um korrigierte Eingabe bitten

Fehlende Abhängigkeiten

Wenn erforderliche Pakete fehlen:

Fehlende Pakete auflisten
Hinzufügen zu package.json anbieten
Installationsbefehl bereitstellen

Output-Format

Erfolgs-Output

✅ API-Endpunkt erstellt: POST /users

Erstellte Dateien:
  📄 src/routes/users.ts
  📄 src/types/users.ts
  📄 tests/routes/users.test.ts

Modifizierte Dateien:
  📝 openapi.yaml (Pfad-Definition hinzugefügt)

Nächste Schritte:
  1. Generierten Code reviewen
  2. Tests ausführen: npm test -- users
  3. Server starten: npm run dev

Fehler-Output

❌ Endpunkt konnte nicht erstellt werden

Problem: Endpunkt POST /users existiert bereits
Ort: src/routes/users.ts:45

Optionen:
  1. Bestehenden Endpunkt aktualisieren: /update-endpoint /users POST
  2. Mit anderem Pfad erstellen: /create-api-endpoint /users/new POST
  3. Abbrechen


### Phase 4: Testen

Skills brauchen Tests wie Code.

**Unit-Testing**: Individuelle Skill-Komponenten testen
```typescript
describe('create-api-endpoint skill', () => {
  describe('input validation', () => {
    it('akzeptiert gültiges Pfadformat', () => {
      expect(validatePath('/users/:id')).toBe(true);
    });

    it('lehnt Pfad ohne führenden Slash ab', () => {
      expect(validatePath('users/:id')).toBe(false);
    });

    it('lehnt ungültige HTTP-Methoden ab', () => {
      expect(validateMethod('INVALID')).toBe(false);
    });
  });

  describe('endpoint generation', () => {
    it('generiert korrekte Dateistruktur', async () => {
      const result = await generateEndpoint({
        path: '/users/:id',
        method: 'GET'
      });

      expect(result.files).toContain('src/routes/users.ts');
      expect(result.files).toContain('src/types/users.ts');
      expect(result.files).toContain('tests/routes/users.test.ts');
    });
  });
});

Integrations-Testing: Skill in realistischen Szenarien testen

describe('create-api-endpoint integration', () => {
  beforeEach(async () => {
    // Test-Projektstruktur aufsetzen
    await createTestProject();
  });

  it('erstellt vollständigen Endpunkt in bestehendem Projekt', async () => {
    const result = await invokeSkill('create-api-endpoint', {
      path: '/products/:id',
      method: 'GET'
    });

    // Dateien existieren verifizieren
    expect(await fileExists('src/routes/products.ts')).toBe(true);

    // Code kompiliert verifizieren
    expect(await runTypeCheck()).toPass();

    // Tests bestehen verifizieren
    expect(await runTests('products')).toPass();
  });
});

Phase 5: Dokumentation

Skills brauchen Dokumentation für Benutzer und Maintainer.

Benutzer-Dokumentation:

# API-Endpunkt erstellen

Erstellt einen vollständigen API-Endpunkt mit TypeScript-Typen, Tests und Dokumentation.

## Nutzung

/create-api-endpoint /pfad METHODE [optionen]


## Beispiele

Einfacher GET-Endpunkt:

/create-api-endpoint /users GET


POST-Endpunkt ohne Auth:

/create-api-endpoint /public/webhook POST —no-auth


Endpunkt mit benutzerdefiniertem Rate-Limit:

/create-api-endpoint /search GET —rate-limit 10


## Optionen

| Option | Standard | Beschreibung |
|--------|----------|--------------|
| --no-auth | false | Authentifizierungsanforderung überspringen |
| --rate-limit N | 100 | Anfragen pro Minute |
| --no-tests | false | Test-Generierung überspringen |

## Generierte Dateien

- `src/routes/{resource}.ts` - Route-Handler
- `src/types/{resource}.ts` - TypeScript-Typen
- `tests/routes/{resource}.test.ts` - Unit-Tests
- Aktualisiert `openapi.yaml` mit Endpunkt-Definition

## Fehlerbehebung

**"Endpunkt existiert bereits"**
Nutze `/update-endpoint` um bestehende Endpunkte zu modifizieren.

**"Ungültiges Pfadformat"**
Pfade müssen mit `/` beginnen und `:param` für Variablen verwenden.

Phase 6: Verteilung

Skills zu Entwicklern zu bringen erfordert eine Verteilungsstrategie.

Repository-Verteilung:

skills-library/
├── official/
│   ├── create-api-endpoint/
│   │   ├── skill.md
│   │   ├── README.md
│   │   └── CHANGELOG.md
│   └── ...
├── community/
│   └── ...
└── experimental/
    └── ...

Best Practices

Fehlerbehandlung

Skills müssen Fehler graceful behandeln. Benutzer sollten nie kryptische Fehlermeldungen sehen.

Prinzip: Jeder Fehler sollte erklären, was schiefgegangen ist, warum, und wie es behoben werden kann.

## Fehler: Projektkonfiguration konnte nicht gelesen werden

Was passiert ist:
  Konnte package.json im aktuellen Verzeichnis nicht finden.

Warum das wichtig ist:
  Dieser Skill muss Ihre Projektstruktur verstehen, um Code zu generieren,
  der zu Ihren Mustern passt.

Wie zu beheben:
  1. Stellen Sie sicher, dass Sie im Projekt-Root-Verzeichnis sind
  2. Führen Sie aus: cd /pfad/zu/ihrem/projekt
  3. Versuchen Sie den Befehl erneut

Alternative:
  Projektpfad angeben: /create-api-endpoint /users GET --project /pfad/zum/projekt

Versionierung

Verwende semantische Versionierung für Skills:

Major (2.0.0): Breaking Changes an Eingaben, Ausgaben oder Verhalten
Minor (1.1.0): Neue Features, abwärtskompatibel
Patch (1.0.1): Bugfixes, Dokumentations-Updates

Abwärtskompatibilität

Bei Skill-Updates, Abwärtskompatibilität aufrechterhalten:

Eingaben nicht entfernen - Stattdessen deprecaten
Output-Orte nicht ändern - Neue Outputs neben alte hinzufügen
Standard-Verhalten nicht ändern - Feature-Flags für neues Verhalten verwenden
Migrationspfade bereitstellen - Dokumentieren wie Nutzung zu aktualisieren

Erste Schritte

Bereit, Ihren ersten Skill zu erstellen?

Kandidaten identifizieren: Einen Workflow wählen, den Sie häufig machen und der von Standardisierung profitieren würde
Zuerst designen: Eingaben, Ausgaben und Fehlerfälle skizzieren bevor implementiert wird
Einfach beginnen: Minimale Version bauen, dann iterieren
Gründlich testen: Skills brauchen Tests wie Produktionscode
Gut dokumentieren: Benutzer und Maintainer brauchen klare Dokumentation

Für Teams, die strukturierte Anleitung zum Aufbau von Skill-Bibliotheken wünschen, erfahren Sie mehr über unsere Beratungsleistungen oder erkunden Sie unseren Leitfaden zur Claude Code Plugin-Architektur.

Dieser Artikel ist Teil unserer Plugin-Architektur-Serie. Für Integration mit externen Systemen siehe MCP-Server-Integrations-Leitfaden. Für Prompt-Standardisierung lesen Sie Prompt-Templates für Entwicklungsteams.