API Conventions Free Claude Code skill, copy & paste

No disable-model-invocation here: this is knowledge, so Claude should load it by itself whenever it builds an endpoint. The description is what it matches on.

---
name: api-conventions
description: REST API conventions for this codebase. Use when creating or changing an HTTP endpoint, a request or response model, or API error handling.
---

# API conventions

Follow these for every endpoint. Where existing code disagrees, these win
for new code; do not rewrite old endpoints unless asked.

## Routes
- Plural nouns, kebab-case: `/api/order-items/{id}`
- No verbs in paths. Actions that are not CRUD are sub-resources:
  `POST /api/orders/{id}/cancel`

## Responses
- 200 with a body, 201 with a `Location` header on create, 204 on delete
- 400 for a malformed request, 404 for a missing resource, 409 for a
  conflict, 422 for a request that is well-formed but invalid
- Errors use the shape in [errors.md](errors.md) — never a bare string

## Models
- camelCase JSON, ISO 8601 UTC timestamps, ids as strings
- Never return a database entity directly; map to a response model

## Before finishing
- Add or update the integration test for the endpoint
- Update the OpenAPI description if the project has one

Skills can bundle more files. SKILL.md links to them and Claude reads them only when needed, so detail costs nothing until it is used.

# Error response shape

Every 4xx and 5xx returns RFC 9457 problem details:

```json
{
  "type": "https://example.com/problems/out-of-stock",
  "title": "Item is out of stock",
  "status": 409,
  "detail": "SKU 4411 has 0 units available; 3 were requested.",
  "instance": "/api/orders/8812"
}
```

- `title` is stable per `type`; `detail` is specific to this occurrence
- Never include stack traces, SQL or internal hostnames
- Validation errors add an `errors` object: field name → list of messages

The folder name becomes the command. Claude Code watches the skills folders, so a new skill is usually available without a restart.

# this project — commit it to share with the team
mkdir -p .claude/skills/api-conventions
mv SKILL.md .claude/skills/api-conventions/

# or: for you, in every project
mkdir -p ~/.claude/skills/api-conventions
mv SKILL.md ~/.claude/skills/api-conventions/

# then, inside Claude Code:
#   add a GET /api/invoices/{id} endpoint   (Claude loads the skill itself)