API Conventions
House REST rules Claude applies when designing endpoints: URL shape, data/error/meta, 422
Test report
- Verdict
- Tested · Works
- Score
- Tested
- Jul 21, 2026
- Environment
- Claude Code 2.x (agent harness)
- Upstream re-checked
- Aug 10, 2026 · 1b565f0
Installed into a throwaway HOME=$(mktemp -d) and confirmed SKILL.md landed at ~/.claude/skills/api-conventions/SKILL.md; frontmatter parsed with yaml.safe_load (name, 273-char description, allowed-tools Read/Grep/Glob), body is 1231 chars referencing zero external files, and a grep for curl|base64|eval|http://|/Users/ found nothing. Same task twice — "design endpoints for listing a customer's coupons and redeeming one" — baseline.md vs skill.md in scratchpad: baseline returned a bare {"coupons":[...],"page","per_page","total"} object, POST /api/coupons/{code}/redeem returning 200, and 409/410 for already-redeemed/expired; the skill version returned {"data":[...],"error":null,"meta":{page,limit,total}} on every response, moved the action to POST /api/v1/coupons/{code}/redemptions returning 201, collapsed 409 and 410 into 422, added a 403 ownership case, and made auth explicit as Bearer + an @public annotation on the one open endpoint. Trigger phrasings I judged load: "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?"; judged no-load: "write a Python client that calls the Stripe API and retries on 429" (consuming, not designing) and "the /users endpoint returns 500, help me find the null deref" (runtime debugging, not format) — 5/5 correct. Real caveat: it is a course demo, so the conventions are hardcoded to one author's house style and half the body prose is Chinese.
Scored on four weighted criteria — install, triggering, output vs. baseline, docs. How scoring works
- Installs cleanly 5/5
- Triggers reliably 5/5
- Output vs. baseline 7/10
- Docs & honesty 4/5
What API Conventions does
A reference skill that loads a fixed set of REST conventions when Claude writes or reviews API endpoints: plural kebab-case resource URLs with max two nesting levels, a mandatory data/error/meta response envelope, a status-code table that routes business-logic failures to 422, Bearer auth with an @public opt-out, and /api/v1 path versioning. It triggers on requests to design a new endpoint, pick a response format, or review an existing route's shape and error responses. The rules are hardcoded and opinionated, so fork the SKILL.md and swap in your own standards before using it on a real project.
How to install API Conventions
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).
Skills live in ~/.claude/skills/ (global) or .claude/skills/
(per-project). Restart Claude Code after installing.
Commands — how to trigger API Conventions
-
/api-conventionsHouse REST rules Claude applies when designing endpoints: URL shape, data/error/meta, 422
It also activates on plain-language prompts like these:
-
Design a new endpoint following our API conventions -
Review this API for consistent error handling -
Check this response format against our standards
Frequently asked questions
- Is the API Conventions skill free?
- Yes. The skill itself is free from huangjia2019/claude-code-engineering. SkillProof publishes the install command and an independent test verdict at no cost.
- Does API Conventions work with Claude Code?
- We tested it with Claude Code 2.x (agent harness) on Jul 21, 2026. Verdict: Tested · Works. Installed into a throwaway HOME=$(mktemp -d) and confirmed SKILL.md landed at ~/.claude/skills/api-conventions/SKILL.md; frontmatter parsed with yaml.safe_load (name, 273-char description, allowed-tools Read/Grep/Glob), body is 1231 chars referencing zero external files, and a grep for curl|base64|eval|http://|/Users/ found nothing. Same task twice — "design endpoints for listing a customer's coupons and redeeming one" — baseline.md vs skill.md in scratchpad: baseline returned a bare {"coupons":[...],"page","per_page","total"} object, POST /api/coupons/{code}/redeem returning 200, and 409/410 for already-redeemed/expired; the skill version returned {"data":[...],"error":null,"meta":{page,limit,total}} on every response, moved the action to POST /api/v1/coupons/{code}/redemptions returning 201, collapsed 409 and 410 into 422, added a 403 ownership case, and made auth explicit as Bearer + an @public annotation on the one open endpoint. Trigger phrasings I judged load: "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?"; judged no-load: "write a Python client that calls the Stripe API and retries on 429" (consuming, not designing) and "the /users endpoint returns 500, help me find the null deref" (runtime debugging, not format) — 5/5 correct. Real caveat: it is a course demo, so the conventions are hardcoded to one author's house style and half the body prose is Chinese.
- What is the API Conventions SkillProof Score?
- 8.4/10 — installs cleanly 5/5, triggers reliably 5/5, output vs. baseline 7/10, docs & honesty 4/5.
- How do I install API Conventions?
- Copy the install command from this page, run it in your terminal, and restart Claude Code. Skills live in ~/.claude/skills/ (global) or .claude/skills/ inside a project.
- Can I use API Conventions with Cursor, Copilot, Gemini CLI, Codex or other AI tools?
- The SKILL.md format is native to Claude (Claude Code, Desktop, claude.ai). The instructions inside adapt to other assistants: Cursor rules, GitHub Copilot instructions, Windsurf rules, Custom GPTs, AGENTS.md for OpenAI Codex, and GEMINI.md for Google Gemini CLI — our conversion guides cover each, and the free converter on the tools page does the wrapping for you.