api-design
/api-design
Use for designing REST/GraphQL API contracts before implementing, and for planning breaking-change version transitions (v1→v2, deprecations). No code edits.
- Author
- mtvrkan ↗
- Repository
- senior-dev-kit ↗
- Licence
- MIT
- Last repository change
- 05.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 05.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use for designing REST/GraphQL API contracts before implementing, and for planning breaking-change version transitions (v1→v2, deprecations). No code edits.
Arguments
/api-design [endpoint or resource to design or version]
Original author description
Use for designing REST/GraphQL API contracts before implementing, and for planning breaking-change version transitions (v1→v2, deprecations). No code edits.
How it works
- Version transitions (breaking changes only)
- Output
SKILL.md preview
---
name: api-design
description: Use for designing REST/GraphQL API contracts before implementing, and for planning breaking-change version transitions (v1→v2, deprecations). No code edits.
allowed-tools: Read, Grep, Glob, Bash
when_to_use: Use automatically before any new API endpoint, when API shape is unclear, or when a change breaks existing clients (removed/renamed field, new required field, error-format/auth change).
argument-hint: "[endpoint or resource to design or version]"
---
# api-design
Design the API contract. No code edits, no implementation — wait for confirmation before coding.
1. Read 1-2 existing endpoints. Extract URL pattern, response envelope, error shape, auth mechanism, status codes — match ALL in the new design.
2. Changing an EXISTING endpoint → grep for callers first. Non-breaking → propose a backwards-compatible alternative. Breaking → version transition below.
## Version transitions (breaking changes only)
Breaking = removed/renamed field, required field added, type/status-code/error-format/auth changed, endpoint removed. Non-breaking (no versioning): new optional field/param, new endpoint.
Plan: current `/api/v[N]` → new `/api/v[N+1]`, both live in parallel — never remove old behavior on deploy. Old version gets `Deprecation` + `Sunset` + `Link` headers; sunset ≥6 months after v[N+1] ships. Write `docs/api-migration-vN-to-vN+1.md`, update OpenAPI spec, regenerate types.
Deep reference: `${CLAUDE_PLUGIN_ROOT}/agent_docs/api-versioning-guide.md` — parallel routing code, deprecation headers, migration guide template, OpenAPI dual-version strategy.
## Output
```text
ENDPOINT: [METHOD] [/path/:param] | AUTH: [guard name | none | role:admin]
REQUEST: headers / params / body (with types) | RESPONSE 200/201: { field: type } ← match existing envelope
ERRORS: 400/401/403/404 — when each applies | IDEMPOTENCY: [required|not] | RATE LIMIT: [required|not]
BREAKING CHANGE RISK: [none|low|HIGH→mitigation] | OPEN QUESTIONS: [none|must-answer]
```
Every mutating endpoint needs auth. Sensitive endpoints must be rate-limited. Never implement — wait for "go".
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · mtvrkan/senior-dev-kit | 95 | MIT |
| proyecto26/system-design-skills | 100 | MIT |
| ericrisco/rsc-harness | 100 | MIT |
| Sanit-mann/The-Insectoids | 100 | MIT |
| yonatangross/orchestkit | 100 | MIT |
| travisjneuman/.claude | 100 | MIT |
| wrongstack/wrongstack | 100 | MIT |
| jelvodev/yaap | 100 | MIT |
| komluk/scaffolding | 100 | MIT |
Database snapshot: 13.11.2026 · package version 5bdadc3f9cfd (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
- 100designing-apis
Designs REST and GraphQL APIs including endpoints, error handling, versioning, and documentation. Use when creating new APIs, designing endpoints, reviewing API contracts, or when asked about REST, GraphQL, or API patterns. - 100design-api
Design REST and GraphQL APIs: naming, versioning, error shapes, auth. Use when "design an API", "create endpoints", "REST vs GraphQL", or "API contract". - 95api-design-principles
Use when designing a new REST or GraphQL API, reviewing an API spec before implementation, setting team API standards, or migrating REST to GraphQL. Covers resources, HTTP semantics, pagination, error handling, and pitfalls. - 100api-versioning
Version REST and GraphQL APIs. Use when a user asks to version an API, handle breaking changes, implement API deprecation, manage multiple API versions, or design an API evolution strategy. - 100create-api-design
Design a REST or GraphQL API from a feature specification when the user asks to design an API, create endpoints, define an API contract, or plan API resources - 100api-and-interface-design
指导稳定的 API 和接口设计。设计 API、模块边界或任何公共接口时使用。创建 REST 或 GraphQL endpoint、定义模块之间的类型契约,或建立前后端边界时使用。