Draft an OpenAPI 3.1 contract from a feature brief or story — resource-oriented paths, a full error catalog (RFC 9457), pagination/idempotency/versioning decided not deferred, examples on every operation, plus a decisions log so review argues choices instead of YAML. Use when the user wants to design an API, draft an OpenAPI/Swagger spec, define request/response shapes, or agree a contract between frontend/backend or two teams before code.
In Claude Code, with the solution-architect plugin installed, invoke it as:
/solution-architect:api-contract-draft
Try it
A realistic prompt from the skill's acceptance evals:
Draft the OpenAPI contract for our orders API — clients need to create an order, fetch one, and list a customer's orders.
What a good result looks like
The YAML validates. OpenAPI 3.1, parseable, refs resolve. A contract that doesn't lint is a sketch.
Every operation enumerates its 4xx set with stable code values a client can switch on. "400: Bad Request" alone is an unwritten error contract.
Every decision in the log has a rationale, and every deviation from reference.md conventions is logged as a decision — silent deviation is how two services end up with three pagination styles.
Examples look like production data."id": "string" in an example means nobody pictured a real call.
No float money, no naked timestamps, no stringly-typed enums. The three classic contract regrets, all preventable at draft time.
Unsafe operations state their idempotency story. A reviewer can answer "what happens on retry?" for every POST.
How it's checked
Measured against plain Claude Code (2026-10-23): it met 85% of its checks, against 40% without it, and a blind judge preferred it. How skills are checked
20 assertions across 3 acceptance evals, and 8 trigger queries. Every skill's checks
What the output must do
The emitted YAML is parseable OpenAPI 3.1 and every $ref resolves
Paths are resource-oriented rather than RPC-style verbs in the URL
Every operation enumerates its 4xx set with stable machine-switchable code values — not a bare '400: Bad Request'
Errors follow RFC 9457 problem-details shape
Pagination, idempotency, and versioning are each decided explicitly rather than deferred
Every operation carries at least one example
Each decision in the log has a rationale, and any deviation from the skill's conventions is logged rather than made silently
Saves openapi.yaml, which parses as YAML and declares an OpenAPI 3.1.x version
Cancelling does not erase the booking: cancelled bookings are kept (for example as a status change), and the reply explains this against the policy's 24-month retention rule instead of silently building the requested delete-everything behaviour
Notices that the brief's 30-minute slots conflict with the policy's 15-minute increments (minimum 30 minutes, maximum 4 hours) and says which the contract follows
The list-bookings operation supports paging, or the reply explains why it is needed, given one group made 412 bookings last year despite the app team's 'few items' claim
Defines how a re-sent booking request is handled so that a dropped connection does not create a duplicate booking
Does not define endpoints that create or edit rooms; rooms are referenced by ID from the existing Facilities API
Does not invent business rules or fields not in the brief or policy without marking them as assumptions
Delivers a usable draft straight away rather than stopping to ask questions
Covers the timing company sending results to the club, with the fields each result carries
Says what happens when a result is re-sent or corrected (the runner's result is updated, not duplicated)
Includes a way for the club to know the sender really is the timing company, explained in plain terms
Does not invent features beyond results (registration, payments, merchandise) or facts such as the race date; anything assumed is marked as an assumption
Is short (about a page or less) and explains the endpoints in plain words a non-developer can pass on
When it should and shouldn't activate
Should activate:
Draft the OpenAPI spec for this API
Write the REST contract for these endpoints
I need an API contract with a proper error catalog and pagination decided
Turn this user story into an OpenAPI 3.1 definition
Should leave to another skill:
Define the contract for this Kafka topic our team publishes
Design the Postgres schema and indexes for this feature
What latency and availability targets should this service have?