Wenn Sie jemals unvollständige, inkonsistente und veraltete Dokumentation geerbt haben, kennen Sie das Problem: Teams erstellen Dokumente mit guten Absichten, aber ohne strenge Überprüfung erodiert die Klarheit. API-Parameter bleiben undokumentiert. Fehlerantworten fehlt die Anleitung. Beispiele funktionieren stillschweigend nicht mehr. Die Terminologie driftet über Dateien hinweg.
Claude Code Skills lösen dies systematisch. Diese KI-gestützten Workflows überprüfen Ihr gesamtes Dokumentations-Repository, identifizieren Lücken und Inkonsistenzen und wenden Korrekturen direkt an. Sie beschreiben, was überprüft werden muss, und Claude generiert einen strukturierten Audit, wendet Verbesserungen an und validiert die Vollständigkeit – alles von Ihrem Terminal aus.
Technische Dokumentation umfasst API-Spezifikationen, Benutzerhandbücher, Bereitstellungshandbücher und Release Notes. Claude Code automatisiert die Überprüfung all dessen. Speziell für die API-Dokumentation kombinieren Sie es mit Apidog für visuelle Validierung und Vollständigkeitsbewertung.
Claude Code Skills für die Dokumentation verstehen
Was sind Dokumentations-Skills?
Claude Code Skills sind benutzerdefinierte, wiederverwendbare KI-Workflows, die die Dokumentationsfunktionen von Claude Code erweitern. Betrachten Sie sie als intelligente Dokumentationsprüfer, die Folgendes können:
- Ihr gesamtes Dokumentations-Repository lesen und den Kontext verstehen
- Spezifikationen mit Implementierungen und Anleitungen abgleichen
- Fehlende Abschnitte, unklare Sprache und Inkonsistenzen identifizieren
- Spezifische Verbesserungen mit Dateipfaden und Zeilennummern vorschlagen
- Korrekturen direkt auf Ihre Dateien anwenden und Änderungen validieren
Im Gegensatz zu traditionellen Lintern, die die Syntax prüfen, nutzen Skills die Denkfähigkeit von Claude, um semantische Probleme zu verstehen – vage Beschreibungen, fehlende Fehlerdokumentation, inkonsistente Beispiele.
Wie Skills funktionieren
Skills arbeiten über mehrere Mechanismen:
1. Vom Benutzer aufrufbare Befehle
# Führen Sie einen Skill mit einem Slash-Befehl aus
/review-docs --completeness
/check-consistency --terminology
/validate-api-specs
/update-broken-examples
2. Erlaubte Tools
Skills geben an, welche Tools sie verwenden dürfen:
Bash: Validierungsbefehle ausführenRead,Write,Edit: Dokumentationsdateien verwaltenGlob,Grep: Dokumente durchsuchenWebFetch: Externe Referenzen abrufenTask: Unteraufgaben für komplexe Überprüfungen erstellen
3. Planungsdateien
Skills pflegen den Status mithilfe von Markdown-Dateien, um den Überprüfungsfortschritt, identifizierte Probleme und angewendete Korrekturen zu verfolgen.
Warum Skills bei der Dokumentationsprüfung hervorragend sind
Die traditionelle Dokumentationsprüfung ist manuell und inkonsistent. Skills bringen Intelligenz und Skalierbarkeit:
- Ganzheitliches Verständnis: Überprüft alle Dateien, erfasst dateiübergreifende Muster
- Konsistente Standards: Wendet dieselben Qualitätskriterien auf jede Datei an
- Kontextbezogene Vorschläge: Versteht, warum etwas falsch ist, nicht nur, dass es falsch ist
- Automatisierung: Kann kontinuierlich überprüfen, während sich die Dokumentation weiterentwickelt
- Geschwindigkeit: Analysiert Hunderte von Seiten in Minuten im Vergleich zu Stunden manueller Überprüfung
Kernfunktionen der Dokumentationsprüfung
1. Vollständigkeitsanalyse
Anweisung: "Prüfen Sie die API-Dokumentation auf Vollständigkeit. Überprüfen Sie jeden Endpunkt auf: Parameter, Anforderungsbeispiele, alle Fehlerantworten und Ratenbegrenzung."
Claude generiert:
Fehlend vom POST /users Endpunkt:
- [ ] Beschreibungen der Anforderungskörperparameter
- [ ] Dokumentation der Fehlerantworten (400, 401, 409)
- [ ] Informationen zur Ratenbegrenzung
- [ ] Sicherheits-/Authentifizierungsanforderungen
2. Konsistenzprüfung
Anweisung: "Überprüfen Sie /docs/ auf terminologische Konsistenz. Markieren Sie alle Begriffe, die mehrfach mit unterschiedlichen Bedeutungen vorkommen."
Claude identifiziert:
Inkonsistente Terminologie gefunden:
- "API key" vs "access token" vs "auth token" (verwenden Sie einen)
- "endpoint" vs "route" vs "method" (verwenden Sie einen)
- "user object" vs "user resource" (verwenden Sie einen)
3. Querverweis-Validierung
Anweisung: "Vergleichen Sie die OpenAPI-Spezifikation in /api/openapi.yaml mit der Dokumentation in /docs/api/. Markieren Sie alle Endpunkte im Code, die nicht dokumentiert sind, oder dokumentierte, die nicht im Code sind."
Claude erkennt:
Diskrepanzen gefunden:
- POST /api/webhooks dokumentiert, aber nicht in openapi.yaml
- PATCH /api/users existiert im Code, fehlt aber in den Docs
- Antwortschema geändert, aber Beispiel nicht aktualisiert
4. Klarheitsbewertung
Anweisung: "Überprüfen Sie auf Klarheit. Markieren Sie vage Beschreibungen, undefinierte Begriffe und mehrdeutige Anweisungen."
Claude identifiziert:
Klarheitsprobleme:
- Zeile 45: "Set config to appropriate values" – welche Werte?
- Zeile 120: "user object" ohne Schema-Definition verwendet
- Zeile 200: "required fields" – welche?
5. Beispielvalidierung
Anweisung: "Überprüfen Sie alle Codebeispiele. Testen Sie sie gegen das aktuelle API-Schema. Markieren Sie defekte oder veraltete Beispiele."
Claude aktualisiert:
Aktualisierte Beispiele:
- curl-Beispiel: Antwortformat geändert, Payload aktualisiert
- Python-Beispiel: Veralteten Parameter verwendet, korrigiert
- JavaScript-Beispiel: Fehlende Fehlerbehandlung, hinzugefügt
Aufbau eines Dokumentations-Skills
Verzeichnisstruktur
Dokumentations-Skills befinden sich in .claude/skills/ mit diesem Layout:
.claude/
├── skills/
│ ├── docs-completeness/
│ │ ├── SKILL.md # Skill-Manifest
│ │ ├── planning.md # Überprüfungsfortschritt
│ │ └── criteria.md # Qualitätscheckliste
│ ├── api-validation/
│ │ ├── SKILL.md
│ │ └── schemas/ # API-Schemata
│ └── consistency-check/
│ └── SKILL.md
└── skills.md # Index aller Skills
Das SKILL.md Manifest
Jeder Dokumentations-Skill beginnt mit YAML-Frontmatter:
---
name: docs-completeness
version: "1.0.0"
description: Dokumentation auf Vollständigkeit und Klarheit überprüfen
user-invocable: true
allowed-tools:
- Read
- Write
- Grep
- Glob
- Edit
hooks:
SessionStart:
- matcher: command
command: "echo '[Docs Review] Starte Dokumentationsprüfung...'"
Stop:
- matcher: command
command: "echo '[Docs Review] Prüfung abgeschlossen. Ergebnisse oben überprüfen.'"
---
# Skill zur Dokumentationsvollständigkeit
Überprüft technische Dokumentation auf Vollständigkeit und Klarheit.
## Verwendung
```bash
/docs-completeness # Vollständiger Repository-Audit
/docs-completeness --api-only # Nur API-Dokumente
/docs-completeness --section api/endpoints.md # Spezifische Datei
Anweisungen für Claude
Beim Aufruf:
- Umfangserkennung → Ziel-Dateien oder vollständiges Repository bestimmen
- Vollständigkeitsanalyse → Jeden Abschnitt anhand der Checkliste prüfen
- Problem-Sammlung → Alle Probleme mit Fundstellen sammeln
- Priorisierung → Nach Auswirkungen sortieren (fehlend vs. unklar vs. inkonsistent)
- Berichtserstellung → Strukturierte Ergebnisse ausgeben
- Korrekturvorschläge → Spezifische Verbesserungen anbieten
- Validierung → Korrekturen vor Anwendung überprüfen
Ihren ersten Dokumentations-Skill erstellen
Tauchen Sie ein: Wir erstellen ein praktisches Tool zur Überprüfung von API-Dokumenten auf Lücken, um sicherzustellen, dass sie umfassend und entwicklergerecht sind. Stellen Sie es sich als Ihren persönlichen Dokumentations-Enforcer vor.
Schritt 1: Den Skill-Ordner einrichten
Initialisieren Sie die Struktur mit einem einfachen Befehl. Claudes Skills leben an einem speziellen Ort zur einfachen Auffindbarkeit.
Bash
mkdir -p .claude/skills/api-docs-reviewSchritt 2: Das Skill-Manifest schreiben
Erstellen Sie .claude/skills/api-docs-review/SKILL.md:
---
name: api-docs-review
version: "1.0.0"
description: Überprüfung der API-Dokumentation auf Vollständigkeit
user-invocable: true
allowed-tools:
- Read
- Write
- Grep
- Edit
---
# API-Dokumentations-Prüfungs-Skill
Prüft die API-Dokumentation auf Vollständigkeit, Klarheit und Genauigkeit.
## Prüfkriterien
Jeder Endpunkt muss Folgendes haben:
**Grundlegende Informationen**
* Klare Beschreibung, was der Endpunkt tut
* HTTP-Methode und Pfad
* Authentifizierungsanforderungen
**Anforderungsdokumentation**
* Alle Pfadparameter mit Typen und Beschreibungen
* Alle Abfrageparameter mit Standardwerten und Einschränkungen
* Anforderungs-Body-Schema (für POST/PUT/PATCH)
* Anforderungen an den Content-Type-Header
* Beispielanforderung (curl oder sprachspezifisch)
**Antwortdokumentation**
* Erfolgsantwort (200/201) mit Schema und Beispiel
* Alle Fehlerantworten (400, 401, 403, 404, 409, 429, 500) mit Beispielen
* Informationen zur Ratenbegrenzung
* Antwort-Header (falls relevant)
**Zusätzlich**
* Verwandte Endpunkte oder Anleitungen
* Versionshistorie, falls zutreffend
* Deprecation Warnings (falls veraltet)
## Anweisungen
Beim Aufruf:
1. **Endpunktdateien scannen** in /docs/api/
2. **Jeden Endpunkt prüfen** anhand der Prüfkriterien
3. **Fehlende Elemente protokollieren** mit spezifischen Datei-/Zeilenreferenzen
4. **Klarheitsprobleme identifizieren** (vage Beschreibungen, undefinierte Begriffe)
5. **Konsistenzprobleme markieren** (Terminologie-Drift, Formatunterschiede)
6. **Checkliste der benötigten Korrekturen generieren**
7. **Anbieten, Korrekturen anzuwenden** mit Beispielen
Berichtsformat:
ENDPUNKT: POST /api/users Datei: docs/api/users.md Status: 65% vollständig
Fehlend:
- [ ] Dokumentation der Fehlerantworten (400, 401, 409)
- [ ] Informationen zur Ratenbegrenzung
- [ ] Definition des Anforderungs-Body-Schemas
Probleme:
- Zeile 45: "user object" undefiniert - Link zum Schema hinzufügen
- Zeile 60: Beispiel veraltet - Antwortformat geändert
Korrekturen verfügbar: Ja (um Anwendung bitten)
Schritt 3: Den Skill registrieren
Zu .claude/skills.md hinzufügen:
# Verfügbare Dokumentations-Skills
## API-Dokumentation
### /api-docs-review
Prüft die API-Dokumentation auf Vollständigkeit anhand von Standardkriterien.
- **Version**: 1.0.0
- **Verwendung**: `/api-docs-review [--file PATH] [--endpoint NAME]`
- **Wann zu verwenden**: Vor der API-Veröffentlichung, nach Codeänderungen
- **Zeit**: 5-10 Minuten für eine mittelgroße API
Schritt 4: Den Skill testen
# In Claude Code
/api-docs-review
Claude wird nun systematisch Ihre API-Dokumentation überprüfen.
Fortgeschrittene Dokumentationsmuster
Muster 1: Nachverfolgung versionierter Dokumentation
Skills können die Dokumentationsqualität über Versionen hinweg verfolgen:
## Versionshistorie
### v2.0.0 [2026-01-22]
Vollständigkeit: 95% ✅
- Alle Endpunkte dokumentiert
- Fehlerantworten vollständig
- Beispiele aktualisiert
- Veraltete /v1 Endpunkte markiert
### v1.0.0 [2025-12-01]
Vollständigkeit: 70%
- Fehlende Fehlerdokumentation
- Veraltete Beispiele
- Keine Veraltungs-Warnungen
Claude erkennt Verbesserungen im Laufe der Zeit.
Muster 2: API-Spezifikationsvalidierung gegen Code
Skills können OpenAPI-Spezifikationen auf Übereinstimmung mit der Implementierung validieren:
## Spezifikationsvalidierung
Vergleiche /api/openapi.yaml mit dem Code:
1. **Implementierung scannen** nach allen Routen
2. **OpenAPI-Spezifikation prüfen** für jede Route
3. **Fehlende Endpunkte markieren**
4. **Parameter überprüfen** auf Übereinstimmung mit der Implementierung
5. **Beispiele aktualisieren** auf Übereinstimmung mit dem aktuellen Schema
Ergebnis: Spezifikation 100% synchron mit dem Code
Automatisierung mit CI/CD
Dokumentations-Validierungspipeline
Richten Sie automatisierte Prüfungen bei jeder Dokumentationsaktualisierung ein:
# .github/workflows/docs-check.yml
name: Dokumentationsprüfung
on:
push:
paths:
- 'docs/**'
- 'api/openapi.yaml'
pull_request:
paths:
- 'docs/**'
- 'api/openapi.yaml'
jobs:
validate-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Apidog CLI installieren
run: npm install -g apidog-cli
- name: OpenAPI-Spezifikation validieren
run: |
apidog lint api/openapi.yaml
apidog check-completeness api/openapi.yaml --min-score 85
- name: Nach defekten Links suchen
run: |
npm install -g markdown-link-check
find docs -name "*.md" -exec markdown-link-check {} \;
- name: Überprüfen, ob Beispiele gültig sind
run: |
# curl-Beispiele testen
bash scripts/test-curl-examples.sh
- name: PR kommentieren
if: failure()
uses: actions/github-script@v7
with:
script: |
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: '❌ Dokumentationsvalidierung fehlgeschlagen. Überprüfen Sie die Workflow-Protokolle.'
})
Realwelt-Szenario: Vollständigkeit der API-Dokumentation
Lassen Sie uns eine realistische API-Dokumentation auf Vollständigkeit prüfen und Verbesserungen anwenden.
Das Szenario
Sie haben eine sechs Monate alte REST-API-Dokumentation. Sie ist teilweise vollständig, aber es fehlen Fehlerdokumentation, sie ist an einigen Stellen unklar und enthält veraltete Beispiele.
Der Audit
Anweisung an Claude: "Prüfen Sie die Dokumentation in /docs/api/. Überprüfen Sie für jeden Endpunkt: Beschreibung, Anforderungsparameter, Antwortbeispiel und alle Fehlerantworten. Priorisieren Sie Korrekturen nach Auswirkungen."
PRÜFERGEBNISSE
=============
KRITISCH (Fehlende Fehlerdokumentation):
├── POST /api/users – Fehlende Fehlerantworten 400, 401, 409
├── POST /api/auth/login – Fehlende 429 (Ratenbegrenzung) Antwort
└── DELETE /api/resources/{id} – Fehlende 403 (verboten) Antwort
HOCH (Klarheitsprobleme):
├── users.md:45 – "user object" undefiniert
├── auth.md:60 – "Set expiration to appropriate value" – zu vage
└── resources.md:30 – Fehlende Beschreibung des Paginierungs-Cursor-Formats
MITTEL (Veraltete Beispiele):
├── products.md:120 – cURL-Beispiel liefert altes Format
├── orders.md:80 – Python SDK-Beispiel verwendet veralteten Parameter
└── webhooks.md:60 – Node.js-Beispiel ohne Fehlerbehandlung
KONSISTENZ:
├── "API key" vs "access token" – 5 inkonsistente Instanzen
├── Anforderungs-Body-Format – 3 verschiedene Stile über Endpunkte hinweg
└── Fehlerantwort-Schema – 2 Variationen statt 1
Prioritäre Korrekturen: Insgesamt 15
Geschätzter Aufwand: 2-3 Stunden manuell, 15 Minuten mit Claude Code
Die Verbesserungen
Systematisches Anwenden von Korrekturen:
Vorher - POST /api/users (Unvollständig):
## Benutzer erstellen
POST /api/users
Erstellt einen neuen Benutzer.
**Parameter:**
- name: Name des Benutzers
- email: E-Mail des Benutzers
**Antwort:**
```json
{
"id": "usr_123",
"name": "Alice",
"email": "alice@example.com"
}
**Nachher - POST /api/users (Vollständig):**
```markdown
## Benutzer erstellen
`POST /api/users`
Erstellt ein neues Benutzerkonto mit den bereitgestellten Details. Die E-Mail muss eindeutig sein.
### Authentifizierung
Erfordert API-Schlüssel im `Authorization`-Header: `Bearer IHR_API_KEY`
### Anforderungsparameter
| Parameter | Typ | Erforderlich | Beschreibung |
|-----------|------|----------|-------------|
| `name` | string | Ja | Vollständiger Name (2-100 Zeichen) |
| `email` | string | Ja | Gültige E-Mail (muss eindeutig sein) |
| `role` | string | Nein | Rolle: `admin`, `developer`, `viewer`. Standard: `viewer` |
### Anforderungsbeispiel
```bash
curl -X POST https://api.example.com/v1/users \
-H "Authorization: Bearer sk_live_abc123" \
-H "Content-Type: application/json" \
-d '{
"name": "Alice Smith",
"email": "alice@example.com",
"role": "developer"
}'
Antwort (201 Erstellt)
{
"id": "usr_abc123",
"name": "Alice Smith",
"email": "alice@example.com",
"role": "developer",
"created_at": "2026-01-22T10:30:00Z"
}
Fehlerantworten
400 Bad Request - Ungültige Eingabe
{
"error": "validation_error",
"message": "Ungültiges E-Mail-Format",
"field": "email",
"request_id": "req_xyz789"
}
401 Unauthorized - Fehlender/ungültiger API-Schlüssel
{
"error": "unauthorized",
"message": "Ungültiger API-Schlüssel",
"request_id": "req_xyz789"
}
409 Conflict - E-Mail existiert bereits
{
"error": "conflict",
"message": "Benutzer mit dieser E-Mail existiert bereits",
"request_id": "req_xyz789"
}
429 Too Many Requests - Ratenbegrenzt
{
"error": "rate_limited",
"message": "Zu viele Anfragen. Versuchen Sie es in 60 Sekunden erneut.",
"retry_after": 60,
"request_id": "req_xyz789"
}
Ratenbegrenzung
100 Anfragen pro Minute pro API-Schlüssel. Siehe Ratenbegrenzungen.
**Angewandte Verbesserungen:**
- Authentifizierungsanforderungen hinzugefügt
- Alle Parameter mit Einschränkungen dokumentiert
- Vollständiger Erfolg + alle Fehlerantworten
- Produktionsreifes cURL-Beispiel
- Informationen zur Ratenbegrenzung
- Konsistente Formatierung
Claude in Apidog für überragende API-Dokumentation integrieren
💡 Profi-Tipp: Nutzen Sie Claude für aufschlussreiche Überprüfungen von narrativen Dokumenten, während Apidog sicherstellt, dass Ihre API-Spezifikationen absolut solide sind und Lücken mit praktischen Beispielen automatisch füllt.
Vorgeschlagene Anweisung für Claude:"Überprüfen Sie /docs/api/ auf allgemeine Klarheit und Attraktivität. Überprüfen Sie anschließend die Vollständigkeit der Datei /api/openapi.yaml mit Apidog. Heben Sie Inkonsistenzen oder fehlende Elemente hervor, damit ich diese direkt in Apidog beheben kann, bevor ich fortfahre."
Bash
# Schritt 1: Erste Prosa-Überprüfung durch Claude
> /docs-completeness # Gibt Vorschläge für klarere Sprache und Struktur aus
# Schritt 2: API-Spezifikationsvalidierung in Apidog
apidog check-completeness api/openapi.yaml # Markiert Probleme wie unvollständige Schemata oder fehlende Antworten
# Schritt 3: Inhalte automatisch mit Apidogs KI generieren
# (Über die Apidog UI: Einstellungen → AI → Beschreibungen, Beispiele und Zusammenfassungen automatisch generieren)
# Schritt 4: Abschließende Harmonieprüfung mit Claude
> /consistency-check # Stellt sicher, dass Docs und Spezifikation perfekt aufeinander abgestimmt sindDies schafft einen Workflow, bei dem Apidog die strukturierte Spezifikationsvalidierung und Claude Code die Qualität der Prosa übernimmt.
Best Practices für die Dokumentationsprüfung
Kennen Sie Ihr Publikum
Passen Sie die Dokumentationstiefe an die Leser an:
| Zielgruppe | Stil | Beispiel |
|---|---|---|
| Entwickler | Codebeispiele in mehreren Sprachen | cURL, Python, JS |
| DevOps | Bereitstellungsschritte, Konfiguration | Kubernetes YAML-Beispiele |
| Produktteams | Hochrangige Workflows, Diagramme | Feature-Flows mit Screenshots |
| Support | Fehlerbehebung, häufige Probleme | "Fehler 429 bedeutet..." |
Klarheit priorisieren
Schreiben Sie im Aktiv, strukturieren Sie zum Überfliegen:
❌ Vorher: "Die Anfrage wird per POST übermittelt. Die Antwort enthält den Benutzer."
✅ Nachher: "Senden Sie eine POST-Anfrage, um einen Benutzer zu erstellen. Die API gibt den neuen Benutzer zurück."
Immer Beispiele einbeziehen
Abstrakte Konzepte benötigen eine Verankerung. Jeder API-Endpunkt benötigt:
# ✅ Kopierfertig
curl -X GET https://api.example.com/v1/users/usr_123 \
-H "Authorization: Bearer IHR_API_KEY"
Häufige Fallstricke
| Fallstrick | Lösung |
|---|---|
| Jargon-Überladung | Begriffe bei erster Verwendung definieren |
| Veraltete Beispiele | Im CI/CD testen |
| Fehlende Fehlerdokumentation | Alle Fehlercodes dokumentieren |
| Inkonsistente Formatierung | Vorlagen verwenden |
| Defekte Links | Im CI/CD prüfen |
Fazit
Claude Code Skills verwandeln die Überprüfung technischer Dokumentation von einem mühsamen manuellen Prozess in einen intelligenten, automatisierten Workflow. Sie beschreiben, was überprüft werden muss, und Claude prüft Ihr gesamtes Dokumentations-Repository, identifiziert Lücken und Inkonsistenzen und wendet Korrekturen an, während es gleichzeitig Qualitätsstandards einhält.
Kombiniert mit Apidog zur Validierung von API-Spezifikationen erreichen Sie eine umfassende Dokumentationsabdeckung.