api-spec-management
Manage API specifications for apps with external HTTP, WebSocket, gRPC, or other API endpoints, including endpoint additions, request or response shape changes, OpenAPI documentation, and schema synchronization.
Best use case
api-spec-management is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Manage API specifications for apps with external HTTP, WebSocket, gRPC, or other API endpoints, including endpoint additions, request or response shape changes, OpenAPI documentation, and schema synchronization.
Teams using api-spec-management should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/api-spec-management/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How api-spec-management Compares
| Feature / Agent | api-spec-management | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Manage API specifications for apps with external HTTP, WebSocket, gRPC, or other API endpoints, including endpoint additions, request or response shape changes, OpenAPI documentation, and schema synchronization.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# api-spec-management
API specification management for applications with external endpoints.
## Use This Skill When
- An app in `apps/` has HTTP, WebSocket, gRPC, or other external API endpoints.
- Adding a new API endpoint to an existing server.
- Changing request or response shapes of an existing API endpoint.
## Core Principles
- Every external API must have a standardized specification document.
- HTTP REST APIs use OpenAPI 3.0+ with interactive UI (e.g., Swagger UI).
- Event-based APIs (WebSocket, SSE) should be documented inline within the OpenAPI spec where possible. Dedicated tooling (e.g., AsyncAPI) may be introduced when the event surface grows; research at adoption time.
- Specifications must stay synchronized with implementation (TypeScript types and route handlers).
- API spec files live in the owning server package's `docs/` source directory (e.g., `src/docs/`).
## HTTP API Workflow
1. When adding or changing an endpoint, update the OpenAPI spec in the same commit.
2. Define schemas for all request bodies, response bodies, query parameters, and path parameters.
3. Error responses must follow RFC 7807 Problem Details format (see `api-error-standard` skill).
4. Provide interactive documentation (Swagger UI or equivalent) in development mode.
5. Use `$ref` and `components/schemas` for reusable schema definitions.
6. Success responses use the envelope: `{ ok: true, status: number, data: {...} }`.
7. Error responses use the envelope: `{ ok: false, status: number, errors: ProblemDetails[] }`.
## Checklist
- [ ] Every endpoint has request and response schemas defined in the OpenAPI spec.
- [ ] Error response schemas follow RFC 7807 (`ProblemDetails` / `ErrorEnvelope`).
- [ ] Interactive API docs are accessible in development (e.g., `/docs/<api-name>`).
- [ ] TypeScript interfaces match the OpenAPI schemas (field names, types, required flags).
- [ ] SSE endpoints document the `text/event-stream` content type and event payload shape.
- [ ] Binary endpoints document the expected `Content-Type` and `Content-Disposition` headers.
## Anti-Patterns
- Defining only status codes without body schemas.
- Writing a spec once and never updating it as the implementation evolves.
- Coupling rules to a specific tool; choose tooling appropriate to the protocol.
- Duplicating schema definitions instead of using `$ref`.
- Omitting error response schemas.Related Skills
version-management
All packages must have the same version. Use changesets for coordinated version bumps. Never version packages independently.
spec-writing-standard
Use when creating a new SPEC.md or incrementally updating an existing one. Covers both initial authoring and the ongoing incremental-update workflow that keeps the spec live.
spec-first-development
Use before implementing any change that adds, removes, or modifies package behavior, public API, types, or contracts. Ensures the governing spec is updated before code is written and a verification test plan exists.
spec-code-conformance
Mandatory verification loop after any SPEC.md or contract document change. Compares spec against implementation code, fixes code to match spec, repeats until zero discrepancies, then runs regression tests. Spec is always the source of truth — never modify the spec within this workflow.
web-design-guidelines
Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
vitest-testing-strategy
Defines a practical testing strategy for TypeScript and JavaScript using Vitest across unit, integration, and type-level tests. Use when adding features, refactoring, or preventing regressions with fast feedback loops.
vercel-react-native-skills
React Native and Expo best practices for building performant mobile apps. Use when building React Native components, optimizing list performance, implementing animations, or working with native modules. Triggers on tasks involving React Native, Expo, mobile performance, or native platform APIs.
vercel-react-best-practices
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
vercel-composition-patterns
React composition patterns that scale. Use when refactoring components with boolean prop proliferation, building flexible component libraries, or designing reusable APIs. Triggers on tasks involving compound components, render props, context providers, or component architecture. Includes React 19 API changes.
user-request-gate
Use immediately when the user requests any implementation, code change, feature addition, fix, or modification. Gates code writing behind a backlog draft document. Read-only exploration is always permitted.
type-boundary-and-ssot
Applies Robota's preferred workflow for trust-boundary validation, strict typing, quality gates, and owner-based SSOT reuse. Use when adding or reviewing type contracts, boundary parsing, shared contract ownership, or running quality checks.
tdd-red-green-refactor
Kent Beck's TDD workflow. Use when writing new code or modifying existing behavior. Enforces the Red-Green-Refactor cycle with small, verifiable steps.