API Conventions
Interne REST-Regeln, die Claude beim Entwerfen von Endpunkten anwendet: URL-Form, Daten/Fehler/Meta, 422
Getestet · Funktioniert
Was es kann
Eine Referenz-Skill, die einen festen Satz von REST-Konventionen lädt, wenn Claude API-Endpunkte schreibt oder überprüft: Plurale Kebab-Case-Ressourcen-URLs mit maximal zwei Verschachtelungsebenen, ein obligatorisches data/error/meta-Antwort-Envelope, eine Statuscode-Tabelle, die Geschäftslogikfehler an 422 weiterleitet, Bearer-Authentifizierung mit einer @public-Opt-out-Option und /api/v1-Pfadversionierung. Sie wird ausgelöst bei Anfragen zum Entwerfen eines neuen Endpunkts, zur Auswahl eines Antwortformats oder zur Überprüfung der Form und Fehlerantworten einer bestehenden Route. Die Regeln sind fest codiert und meinungsstark, daher forken Sie die SKILL.md und tauschen Sie Ihre eigenen Standards aus, bevor Sie sie in einem realen Projekt verwenden.
Testbericht
Installiert in einem temporären HOME=$(mktemp -d) und bestätigt, dass SKILL.md unter ~/.claude/skills/api-conventions/SKILL.md landete; Frontmatter wurde mit yaml.safe_load geparst (name, 273-Zeichen-Beschreibung, allowed-tools Read/Grep/Glob), der Body ist 1231 Zeichen lang und referenziert keine externen Dateien, und ein grep nach curl|base64|eval|http://|/Users/ fand nichts. Dieselbe Aufgabe zweimal – „Endpunkte für die Auflistung der Coupons eines Kunden und das Einlösen eines Coupons entwerfen“ – baseline.md vs. skill.md im Scratchpad: Baseline gab ein nacktes {"coupons":[...],"page","per_page","total"}-Objekt zurück, POST /api/coupons/{code}/redeem gab 200 zurück, und 409/410 für bereits eingelöste/abgelaufene; die Skill-Version gab {"data":[...],"error":null,"meta":{page,limit,total}} bei jeder Antwort zurück, verschob die Aktion auf POST /api/v1/coupons/{code}/redemptions, das 201 zurückgab, fasste 409 und 410 zu 422 zusammen, fügte einen 403-Besitzfall hinzu und machte die Authentifizierung explizit als Bearer + eine @public-Annotation am einzigen offenen Endpunkt. Trigger-Phrasierungen, die ich als passend beurteilte: „Füge einen REST-Endpunkt zur Auflistung der Rechnungen eines Benutzers hinzu – wie sollten die URL und der Antwort-Body aussehen?“, „Überprüfe diese Express-Route-Datei und sage mir, ob die Fehlerantworten korrekt sind“, „Wir entwerfen eine neue öffentliche Bestell-API – welcher Statuscode für einen Validierungsfehler?“; als unpassend beurteilte: „Schreibe einen Python-Client, der die Stripe-API aufruft und bei 429 wiederholt“ (konsumierend, nicht entwerfend) und „der /users-Endpunkt gibt 500 zurück, hilf mir, den Null-Deref zu finden“ (Laufzeit-Debugging, nicht Format) – 5/5 korrekt. Echter Vorbehalt: Es handelt sich um eine Kursdemo, so sind die Konventionen auf den Hausstil eines Autors fest codiert und die Hälfte des Body-Textes ist Chinesisch.
Getestet am: 2026-07-21 · Claude Code 2.x (agent harness)
Installation
git clone --depth 1 https://github.com/huangjia2019/claude-code-engineering.git /tmp/api-conventions-src
mkdir -p ~/.claude/skills
cp -R /tmp/api-conventions-src/04-Skills/projects/01-reference-skill/.claude/skills/api-conventions ~/.claude/skills/api-conventions
# Single self-contained SKILL.md (~1.7KB), no scripts, no deps, no API keys.
# Source repo is a Chinese course companion ("Claude Code 工程化实战") with 8+ demo skills;
# this slug is the 01-reference-skill example. Parts of the SKILL.md body (response-format
# and status-code notes) are written in Chinese; the rules themselves are language-neutral.
# IMPORTANT: the description says "conventions for this project" but the rules are the course
# author's, not yours. Edit ~/.claude/skills/api-conventions/SKILL.md to match your real
# standards, or it will push /api/v1, data/error/meta envelopes and 422 onto every codebase.
# frontmatter sets allowed-tools: Read, Grep, Glob (read-only). Befehle & Beispiel-Prompts
/api-conventionsInterne REST-Regeln, die Claude beim Entwerfen von Endpunkten anwendet: URL-Form, Daten/Fehler/Meta, 422
Skills reagieren auf normale Anfragen — keine Slash-Befehle nötig. Nach der Installation aktivieren Prompts wie diese den Skill (auf Englisch):
Design a new endpoint following our API conventionsReview this API for consistent error handlingCheck this response format against our standards