Skip to content
Skills Library
Programming · Planning

api-design

/api-design

Use when an API contract is designed or changed: a new endpoint or resource, how its errors and pages are returned, a field to add or remove, or a version to cut without breaking a consumer.

Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
1
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Use when an API contract is designed or changed: a new endpoint or resource, how its errors and pages are returned, a field to add or remove, or a version to cut without breaking a consumer.

Original author description

Use when an API contract is designed or changed: a new endpoint or resource, how its errors and pages are returned, a field to add or remove, or a version to cut without breaking a consumer.

How it works

  1. Checklist
  2. How
  3. Breaking vs additive
  4. Invariant rules
Original SKILL.md headings · 50 lines, 522 words
SKILL.md preview
---
name: api-design
description: |
  Use when an API contract is designed or changed: a new endpoint or resource, how its errors and pages
  are returned, a field to add or remove, or a version to cut without breaking a consumer.
---

# API Design

<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
Trigger phrases: "api design", "api contract", "api versioning", "openapi", "swagger", "rest contract", "breaking api change", "response shape", "response format", "endpoint returns", "error format"

Goal: a contract the consumer can **predict** and that can **evolve** without breaking. Once published, a
public API is a commitment; a breaking change is expensive. Stack-agnostic (REST as the baseline; GraphQL/gRPC follow similar principles).

## Checklist
- [ ] Resource names are **consistent** (plural nouns, a single `kebab`/`camel` style), resources not verbs
- [ ] Correct HTTP semantics: GET (side-effect free) · POST · PUT/PATCH · DELETE; correct **status code**
- [ ] A uniform **error model**: machine-readable code + human message + (if any) field details
- [ ] A clear **versioning** strategy (URL `/v1` or header); a breaking change means a new version
- [ ] **Pagination/filtering/sorting** defined and consistent on large collections
- [ ] **Backward compatibility**: adding a field is additive; removing a field or changing its meaning is breaking → version
- [ ] **Idempotency** (for POST/payment-like cases) supported via a key when needed: the key, its atomic claim and
  the answers to a replay are in **`references/idempotency.md`**
- [ ] The contract is documented in **OpenAPI**; example request/response present (coordinate with `docs-writer`)

## How
1. **Model the resource** — a noun not a verb: `POST /orders` (✓), `POST /createOrder` (✗).
2. **Status codes**: 200/201/204 · 400 validation · 401/403 authorization · 404 · 409 conflict · 422 · 429 · 5xx. Use them meaningfully.
3. **Error contract** — every error has the same shape:
   ```json
   { "code": "ORDER_NOT_FOUND", "message": "Order not found", "details": [] }
   ```
   No stack trace / internal detail leakage (overlaps with `security-scan`).
4. **Versioning**: additive changes in the same version; breaking (remove/rename a field / add a required field) → `/v2`.
5. **Collection**: pagination (cursor or offset), filter/sort parameters; a consistent envelope.
6. **Write the contract** — OpenAPI/schema; with examples. Wire the change to `docs-writer`, and if breaking to `release`/CHANGELOG.

## Breaking vs additive
| Additive (safe) | Breaking (needs a version) |
|---|---|
| Add an optional field/endpoint | Remove / rename a field |
| A new optional parameter | Add a required parameter |
| A new enum value (if the consumer is tolerant) | Change a type/meaning, change a status code |

**Observable behaviour is the contract,** not only the documented fields: someone depends on the error text, the
order of a list, the default page size and how long a call takes. Changing one of those is breaking for them; say
it in the changelog like a field change.

## Invariant rules
1. **A public API is a commitment** — a breaking change is not made silently; version + announcement.
2. **Consistency > local cleverness** — a single naming/error/pagination pattern across the whole API.
3. **The error model is uniform and machine-readable.**
4. **No internal detail leakage** — a stack trace / DB error does not go to the consumer.
5. **The contract is documented** — OpenAPI + example; at design time, not after the code.
Files in this package (2)
  • SKILL.md 4 KB
  • references/idempotency.md 2 KB

Versions

RepositoryScoreLicence
This page · byerlikaya/claude-starter-kit100MIT
proyecto26/system-design-skills100MIT
ericrisco/rsc-harness100MIT
Sanit-mann/The-Insectoids100MIT
yonatangross/orchestkit100MIT
travisjneuman/.claude100MIT
wrongstack/wrongstack100MIT
jelvodev/yaap100MIT
komluk/scaffolding100MIT

Database snapshot: 13.11.2026 · package version 15f0f41d5915 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100api-contract-versioning
    Use when modifying an API endpoint, schema or contract consumed elsewhere - renaming/removing/restructuring a request or response field, pagination or envelope change, "field X must become", "le champ X doit devenir", introducing a breaking change, versioning an API, or…
  • 96add-endpoint
    Add an HTTP endpoint or a new resource to this Quarkus API with its store, error rows and tests. Use when the user asks for a new endpoint, resource, field, query parameter or HTTP method.
  • 96add-endpoint
    Add an HTTP endpoint or a new resource to this Spring Boot API with its store, error rows and tests. Use when the user asks for a new endpoint, resource, field, query parameter or HTTP method.
  • 100quick-api
    Use when scaffolding a new API endpoint — types, test, handler, validation, route, docs
  • 100api-design-standards
    API design discipline grounded in the Microsoft/Google REST guidelines, resource and URL conventions, a chosen versioning strategy, what counts as a backward-compatible vs breaking change, and consumer-driven contract testing. Use when designing a new API endpoint, changing an…
  • 100nacl-tl-sync
    Verify backend and frontend synchronization for a NaCl UC task against the API contract, shared types, endpoint usage, errors, and mock removal. Use when checking BE/FE alignment, API contract compliance, or when the user says `/nacl-tl-sync`.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.