API Conventions
Règles REST internes que Claude applique lors de la conception d'endpoints : forme d'URL, data/error/meta, 422.
Testé · Fonctionne
Ce que fait
Compétence de référence qui charge un ensemble fixe de conventions REST lorsque Claude écrit ou révise des endpoints API : URLs de ressources en kebab-case pluriel avec un maximum de deux niveaux d'imbrication, une enveloppe de réponse data/error/meta obligatoire, une table de codes de statut qui achemine les échecs de logique métier vers 422, authentification Bearer avec une option @public, et versioning de chemin /api/v1. Elle se déclenche sur les demandes de conception d'un nouvel endpoint, de choix d'un format de réponse, ou de révision de la forme et des réponses d'erreur d'une route existante. Les règles sont codées en dur et opinionnées, donc forkez le SKILL.md et remplacez-les par vos propres standards avant de l'utiliser sur un projet réel.
Rapport de test
Installé dans un HOME temporaire=$(mktemp -d) et confirmé que SKILL.md s'est retrouvé dans ~/.claude/skills/api-conventions/SKILL.md ; frontmatter analysé avec yaml.safe_load (name, description de 273 caractères, allowed-tools Read/Grep/Glob), le corps fait 1231 caractères référençant zéro fichiers externes, et un grep pour curl|base64|eval|http://|/Users/ n'a rien trouvé. Même tâche deux fois — "design endpoints for listing a customer's coupons and redeeming one" — baseline.md vs skill.md dans le bloc-notes : la référence a retourné un objet nu {"coupons":[...],"page","per_page","total"}, POST /api/coupons/{code}/redeem retournant 200, et 409/410 pour déjà-utilisé/expiré ; la version de la compétence a retourné {"data":[...],"error":null,"meta":{page,limit,total}} sur chaque réponse, a déplacé l'action vers POST /api/v1/coupons/{code}/redemptions retournant 201, a regroupé 409 et 410 en 422, a ajouté un cas de propriété 403, et a rendu l'authentification explicite comme Bearer + une annotation @public sur le seul endpoint ouvert. Phrases de déclenchement que j'ai jugées pertinentes : "add a REST endpoint for listing a user's invoices — what should the URL and response body look like?", "review this Express route file and tell me if the error responses are right", "we're designing a new public orders API — what status code for a validation failure?"; jugées non pertinentes : "write a Python client that calls the Stripe API and retries on 429" (consommation, pas conception) et "the /users endpoint returns 500, help me find the null deref" (débogage runtime, pas format) — 5/5 correct. Vraie mise en garde : c'est une démo de cours, donc les conventions sont codées en dur selon le style maison d'un auteur et la moitié de la prose du corps est en chinois.
Testé le: 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). Commandes et exemples de prompts
/api-conventionsRègles REST internes que Claude applique lors de la conception d'endpoints : forme d'URL, data/error/meta, 422.
Les skills se déclenchent sur des demandes en langage courant — aucune commande à retenir. Après installation, des prompts comme ceux-ci l'activent (en anglais) :
Design a new endpoint following our API conventionsReview this API for consistent error handlingCheck this response format against our standards