skills.rest
CagesThrottleUs
CagesThrottleUsCOMMUNITY
Explore all skills by this author →
GitHub

api-contract-first

Generates OpenAPI 3.1 or protobuf API contracts with Spectral linting and Prism mock servers before handler implementation.

Updated May 21, 2026
Search Tags:#api design#openapi#protobuf#grpc#contract-first#spectral#prism mock
One-click install
npx skills add https://github.com/CagesThrottleUs/private-ai-harness --skill api-contract-first-cagesthrottleus
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-contract-first
Source: https://github.com/CagesThrottleUs/private-ai-harness/tree/main/skills/api-contract-first
Command: npx skills add https://github.com/CagesThrottleUs/private-ai-harness --skill api-contract-first-cagesthrottleus

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams that write handler code before defining the API end up with contracts designed by accident — the API becomes whatever was convenient to implement rather than what consumers need. This Skill enforces a contract-first workflow where the OpenAPI spec or .proto file is written, linted, reviewed, and approved before any handler code exists. ## Core Features & Use Cases - Contract Generation: Produces a complete OpenAPI 3.1 YAML spec (with RFC 9457 error shapes, pagination, auth schemes) or a versioned .proto file following Google's protobuf style rules. - Linting and Mocking: Sets up a Spectral ruleset for spec linting in CI and a Prism mock server so frontend and backend teams develop in parallel against the same contract. - Review Gates: Dispatches an api-contract-reviewer agent and enforces a human approval gate before handler implementation begins. - Use Case: When a plan adds a new REST endpoint, run this Skill to produce api/openapi.yaml, wire Spectral into CI, start a Prism mock on port 4010, and only begin handler coding after the spec passes review. ## Quick Start Ask the AI to write the OpenAPI contract for the new endpoint defined in the plan before any handler code is written.

Frequently Asked Questions about api-contract-first

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an OpenAPI spec before implementing the API?▼

Define every endpoint, request body, response schema, and error shape in an OpenAPI 3.1 YAML file first, then lint it with Spectral and review it before writing handlers. The handler then implements the approved contract exactly.

What is the difference between OpenAPI and protobuf for API design?▼

OpenAPI 3.1 describes REST/HTTP APIs with JSON payloads, while .proto files define gRPC services with versioned packages and numbered fields. Choose based on the protocol specified in your design document; gateway patterns may need both.

How do I mock an API from an OpenAPI spec for frontend development?▼

Run Prism with 'prism mock api/openapi.yaml --port 4010' to serve example responses from the spec. Frontend developers point their base URL at localhost:4010 while the backend implements the same contract in parallel.

Does Spectral linting work in CI pipelines?▼

Yes, Spectral runs as a CI job using 'spectral lint api/openapi.yaml --ruleset .spectral.yaml' in GitHub Actions or GitLab CI. Any rule violation fails the build before handler code is merged.

When should I skip contract-first API design?▼

Skip it for internal helpers, database queries, background jobs, or when adding a parameter to an endpoint already covered by an existing spec. It is required only for new externally-visible API surfaces.

How do I make breaking changes to a protobuf API?▼

Never reuse field numbers or remove fields without marking them reserved. Breaking changes require a new version package such as v2 rather than modifying the existing package, keeping wire compatibility for existing consumers.

Related Skills

Explore More Software Engineering Skills→
awood45awood45
11

review-design-high-level

Identify gaps in high-level design documents before low-level design begins.

Community
Advanced
latestaiagentslatestaiagents
5

api-test-patterns

Generate Playwright and Pact API tests for REST and GraphQL endpoints.

Official
Advanced
aquariuscookaquariuscook

contract-testing

Automate consumer-driven contract testing for microservices using Pact and schema validation.

Community
Advanced
compozycompozy
2.7k

eng-contract-codegen-coship

Coordinates atomic co-shipping of Compozy wire-contract changes across OpenAPI specs, generated clients, and docs.

Official
Advanced