API Conventions
Interne REST regels die Claude toepast bij het ontwerpen van endpoints: URL structuur, data/error/meta, 422
Getest · Werkt
Wat het doet
Een referentie skill die een vaste set REST conventies laadt wanneer Claude API endpoints schrijft of beoordeelt: meervoudige kebab-case resource URLs met maximaal twee nestniveaus, een verplichte data/error/meta response envelope, een statuscode-tabel die business-logica fouten naar 422 routeert, Bearer auth met een @public opt-out, en /api/v1 padversiebeheer. Het activeert bij verzoeken om een nieuw endpoint te ontwerpen, een response formaat te kiezen, of de vorm en foutresponses van een bestaande route te beoordelen. De regels zijn hardcoded en opiniërend, dus fork de SKILL.md en wissel je eigen standaarden in voordat je het op een echt project gebruikt.
Testrapport
Geïnstalleerd in een tijdelijke HOME=$(mktemp -d) en bevestigd dat SKILL.md terechtkwam in ~/.claude/skills/api-conventions/SKILL.md; frontmatter geparset met yaml.safe_load (name, 273-char description, allowed-tools Read/Grep/Glob), body is 1231 tekens en verwijst naar nul externe bestanden, en een grep naar curl|base64|eval|http://|/Users/ vond niets. Dezelfde taak twee keer — "ontwerp endpoints voor het weergeven van de coupons van een klant en het inwisselen van één" — baseline.md versus skill.md in scratchpad: baseline retourneerde een kaal {"coupons":[...],"page","per_page","total"} object, POST /api/coupons/{code}/redeem retourneerde 200, en 409/410 voor reeds ingewisseld/verlopen; de skill-versie retourneerde {"data":[...],"error":null,"meta":{page,limit,total}} bij elke response, verplaatste de actie naar POST /api/v1/coupons/{code}/redemptions die 201 retourneerde, voegde 409 en 410 samen tot 422, voegde een 403 ownership case toe, en maakte auth expliciet als Bearer + een @public annotatie op het ene open endpoint. Triggerfraseringen die ik als 'load' beoordeelde: "voeg een REST endpoint toe voor het weergeven van de facturen van een gebruiker — hoe moeten de URL en response body eruitzien?", "beoordeel dit Express route bestand en vertel me of de foutresponses correct zijn", "we're designing a new public orders API — what status code for a validation failure?"; als 'no-load' beoordeelde: "schrijf een Python client die de Stripe API aanroept en opnieuw probeert bij 429" (consumerend, niet ontwerpend) en "het /users endpoint retourneert 500, help me de null deref te vinden" (runtime debugging, niet formaat) — 5/5 correct. Echte kanttekening: het is een cursusdemo, dus de conventies zijn hardcoded naar de huisstijl van één auteur en de helft van de bodyproza is Chinees.
Getest op: 2026-07-21 · Claude Code 2.x (agent harness)
Installatie
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). Commando's en voorbeeldprompts
/api-conventionsInterne REST regels die Claude toepast bij het ontwerpen van endpoints: URL structuur, data/error/meta, 422
Skills reageren op gewone verzoeken — geen commando's om te onthouden. Na installatie activeren prompts zoals deze de skill (in het Engels):
Design a new endpoint following our API conventionsReview this API for consistent error handlingCheck this response format against our standards