Use api-contract-draft

Draft an OpenAPI 3.1 contract from a feature brief or story

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.

Reach for it 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.

Install it

npx skilldrop-cli install api-contract-draft                 # Claude Code, your user folder
npx skilldrop-cli install api-contract-draft --project       # Claude Code, this repo
npx skilldrop-cli install api-contract-draft --ide cursor    # or kiro, codex, antigravity, copilot

It is part of the Solution architect pack: --pack solution-architect installs it with its neighbours.

Ask for it

Say it the way you would to a colleague. Requests like these route to it:

• "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"

Requests like these belong to a different skill, so it shouldn't answer them:

• "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?"

If another skill answers instead, ask for this one by name: "use api-contract-draft".

Check what you get

A good result:

• 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.

Use something else when

• Documenting an API that already exists — that's guide-builder (reference archetype)
• Choosing REST vs GraphQL vs gRPC — this skill starts after that choice is made
• An event, message or webhook contract — that's event-contract-draft
• Reviewing a contract someone else drafted — doc-critique or council-review
• Generating server/client code from the spec — hand the frozen contract to the codegen tool

Next

• SKILL.md, the instructions the agent reads
• Its page on the site
• Related: council-review, doc-critique, guide-builder, user-story-splitter, event-contract-draft

Edit this page on GitHub · View source