Claude Skill MartBrowse skillsQuick linesLearn by videoTerminal guideWhat is a Skill?
 
← Back to list

API Design Conventions

A convention sheet that makes Claude enforce consistent REST URL naming, response envelopes, status codes, and auth rules.

Dev & CodingBeginner★ 1,129⑂ 397AI score 7/10Last updated: Jul 23, 2026

What it does

  • Applies your project's API standards whenever endpoints are written or reviewed.
  • Enforces URL naming: plural resources, kebab-case, max two nesting levels, query params for filtering.
  • Standardizes every response into a data / error / meta envelope, with pagination meta required on list endpoints.
  • Defines HTTP status code usage (200/201/400/401/403/404/422/500), auth rules (Bearer token, @public annotation for public routes), and URL-based versioning (/api/v1/...).

Who it's for

  • Backend teams where each developer shapes APIs differently
  • Tech leads repeating the same API review comments every PR
  • Developers bootstrapping conventions for a new service
  • Anyone scaffolding endpoints with Claude Code

Examples

  1. "Add an endpoint to list orders" → produces /api/v1/orders?status=active&limit=20 with the data/error/meta wrapper.
  2. "Review the API changes in this PR" → flags verb/singular URLs like /getUserOrder, missing 401/422 handling, and list responses without meta.
  3. "Can this endpoint be unauthenticated?" → reminds you to mark it @public and document it.

· · · Install guide · · ·

Try it now, no install

Paste this into Claude to use the skill without installing anything.

Read the instructions in this file and follow them to help me:
https://raw.githubusercontent.com/huangjia2019/claude-code-engineering/HEAD/04-Skills/projects/01-reference-skill/.claude/skills/api-conventions/SKILL.md

What I want: (describe your task here)

If Claude can't open the link, open it yourself and paste the contents instead.

↓ If it works for you, download the ZIP below and install it. Then it runs on its own — no pasting each time.

Install in the Claude app (no terminal)
  1. Download the ZIP with the button below.
  2. In Claude, open Settings → Capabilities and turn on 'Code execution and file creation'. (one time)
  3. Go to Customize → Skills → + → 'Upload a skill' and upload the ZIP.
↓ Download ZIP
Install in Claude Code

Let Claude do it — paste this into Claude Code

Install the skill I found on Claude Skill Mart.
Copy the 04-Skills/projects/01-reference-skill/.claude/skills/api-conventions folder from the GitHub repo huangjia2019/claude-code-engineering into my ~/.claude/skills/api-conventions/.
When it's done, tell me in one line what this skill can do.

Install with a command instead

git clone https://github.com/huangjia2019/claude-code-engineering.git && mkdir -p ~/.claude/skills/api-conventions && cp claude-code-engineering/04-Skills/projects/01-reference-skill/.claude/skills/api-conventions/SKILL.md ~/.claude/skills/api-conventions/

⚠ This is a third-party skill. Check the source repository before installing.

  1. Open a terminal.
  2. Clone the repo: git clone https://github.com/huangjia2019/claude-code-engineering.git
  3. Create the skill folder: mkdir -p ~/.claude/skills/api-conventions
  4. Copy the file: cp claude-code-engineering/04-Skills/projects/01-reference-skill/.claude/skills/api-conventions/SKILL.md ~/.claude/skills/api-conventions/
  5. (Recommended) Edit SKILL.md so the response format, status codes, and auth rules match your team's real standards.
  6. Restart Claude Code and try: "Review this endpoint against our API conventions."
  7. To scope it to one repo only, place the file in that project's .claude/skills/ instead of ~/.claude.
View source on GitHub ↗