# API Design

> Shape a contract so inputs, outputs, errors, names, and compatibility are clear and hard to misuse.

- Skill: `nevitonsantana/api-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nevitonsantana/api-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nevitonsantana/api-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: nevitonsantana (https://skillmd.com/u/nevitonsantana)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nevitonsantana/api-design

---


# Overview

Use this skill to design or review interfaces between systems or modules with clarity and change-awareness.

# When to Use

- new endpoints or interfaces
- payload redesign
- public or semi-public contract changes

# When NOT to Use

- private local implementation details with no meaningful contract

# Core Moves

1. Name the contract responsibility.
2. Define inputs and outputs.
3. State failure semantics.
4. Review naming for real-world use.
5. Check compatibility cost for consumers.

# Optional Modules

- **Error taxonomy** — Expand failure classes when misuse or recovery matters.
- **Compatibility pass** — Map what breaks for current consumers.
- **Ownership note** — Clarify who owns the contract and its evolution.

# Activation Triggers

- Use the error taxonomy when clients need to react differently to failures.
- Use the compatibility pass when consumers already exist.
- Add ownership when many teams touch the contract.

# Expected Output

- contract statement
- input/output model
- error model
- compatibility note

# Verification

- The contract responsibility is singular.
- Consumers can understand success and failure clearly.
- Backwards-compatibility assumptions are explicit.

# Handoff Signals

- The contract needs product or policy review.
- The change requires coordinated rollout across teams.

# Pairs Well With

- `communication`
- `architecture-review`
- `testing`

# Anti-patterns

- Encoding ambiguity into flexible payloads.
- Changing a contract without naming compatibility cost.
- Optimizing for implementation convenience over consumer clarity.