Api design
Use for designing REST/GraphQL API contracts before implementing, and for planning breaking-change version transitions (v1→v2, deprecations). No code edits.From its SKILL.md
npx -y skills add mtvrkan/senior-dev-kit --skill api-designAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
2.1 KB, as published. Nobody here has run it
api-design
Design the API contract. No implementation — wait for confirmation before coding.
- Read 1-2 existing endpoints. Extract URL pattern, response envelope, error shape, auth mechanism, status codes — match ALL in the new design.
- 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: agent_docs/api-versioning-guide.md — parallel routing code, deprecation headers, migration guide template, OpenAPI dual-version strategy.
Output
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".