Skill530 repo starsupdated 1mo ago

api-design-reviewer

The API Design Reviewer evaluates proposed REST or GraphQL API changes before merge, checking contract clarity, backwards compatibility, error handling, pagination, authentication, and naming conventions against a standardized checklist. Use it when proposing new endpoints, mutations, or schemas, assessing breaking changes, or needing design review before stakeholder approval.

View source Repository: LLM-Agents-Ecosystem-Handbook

Install in Claude Code

Copy

git clone --depth 1 https://github.com/oxbshw/LLM-Agents-Ecosystem-Handbook /tmp/api-design-reviewer && cp -r /tmp/api-design-reviewer/skills/catalog/api-design-reviewer ~/.claude/skills/api-design-reviewer

Then start a new Claude Code session; the skill loads automatically.

Definition

SKILL.md

# API Design Reviewer

## When to use
- A new endpoint / mutation / schema is being proposed
- A breaking change is on the table
- An API draft needs a second pair of eyes before stakeholder review

## When NOT to use
- Pure implementation details (use `repo-auditor`)
- UI / UX feedback
- Cost / SLA tradeoffs (those need product discussion)

## Inputs
| Name | Type | Required | Notes |
|---|---|---|---|
| `spec` | path or text | yes | OpenAPI / GraphQL SDL / Markdown design doc |
| `mode` | `"public"` \| `"internal"` | no | Default `internal`. `public` raises the bar on backwards-compat. |

## Outputs
A Markdown review with sections: Critical, Important, Nits, Open questions.

## Workflow
1. Parse the spec; list the operations / types touched
2. For each operation, walk `references/api-review-checklist.md`:
   - Naming consistent with neighbors?
   - Resource model coherent?
   - Errors enumerated and typed?
   - Pagination present (where lists are returned)?
   - Auth + authz documented?
   - Idempotency on writes?
   - Versioning strategy?
3. For breaking changes, surface the contract delta explicitly
4. Group findings into **Critical** (blockers), **Important** (should fix), **Nits** (style)
5. Append **Open questions** for the author

## References
- [`references/api-review-checklist.md`](references/api-review-checklist.md)

## Success criteria
- 0 fabricated findings (every finding cites a section of the spec)
- Critical/Important findings have a concrete suggested fix
- Tone is collegial, not pedantic

## Failure modes
- Spec too large (> 200 ops) → split into modules and ask the author which to focus on
- Internal jargon in the spec without definitions → list as Open questions, don't guess

## Examples
- Good: "Critical — `GET /users` returns an unbounded list. Add cursor pagination (suggested: `?cursor=...&limit=...`)."
- Bad: "I think pagination might be useful here."