skills.rest
geekatron
geekatronCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

contract-design

Generates OpenAPI 3.1 contracts from use case interaction artifacts with full traceability.

Updated Jul 2, 2026
Search Tags:#api design#openapi#traceability#rest api#use case#api contract#contract generation
One-click install
npx skills add https://github.com/geekatron/jerry-claude-plugin --skill contract-design-geekatron
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: contract-design
Source: https://github.com/geekatron/jerry-claude-plugin/tree/main/skills/contract-design
Command: npx skills add https://github.com/geekatron/jerry-claude-plugin --skill contract-design-geekatron

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Bridging the gap between behavioral use case specifications and machine-readable API contracts is manual and error-prone. This Skill transforms structured use case realization artifacts into OpenAPI 3.1 specifications, ensuring every API operation traces back to a specific use case interaction step. ## Core Features & Use Cases - UC-to-Contract Transformation: Maps each use case interaction to exactly one API operation, deriving HTTP methods from request semantics per RFC 9110 with confidence annotations. - Schema Derivation: Builds request schemas from interaction preconditions and response schemas from postconditions, and maps failure extensions to 4xx/5xx error responses. - Contract Validation: Runs a 9-step validation protocol verifying structural compliance, 100% traceability coverage, and mandatory PROTOTYPE labeling. - Use Case: After realizing a use case like "Borrow a Book" with defined interactions, generate a complete OpenAPI 3.1 spec plus a traceability mapping document, then validate it before handing it to implementers or code generators. ## Quick Start Ask the AI to generate an OpenAPI contract from your use case artifact at INTERACTION_DEFINED level, for example: "Generate an OpenAPI contract from the use case at projects/PROJ-021/use-cases/UC-AUTH-001-validate-credentials.md".

Frequently Asked Questions about contract-design

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

FAQPage Schema
How do I generate an OpenAPI spec from a use case?▼

Provide a use case artifact at realization_level INTERACTION_DEFINED with a populated interactions block, then invoke the cd-generator agent. It produces an OpenAPI 3.1 YAML file plus a traceability mapping document linking every operation to its source interaction step.

How are HTTP methods inferred from use case descriptions?▼

HTTP methods are inferred from request_description semantics per RFC 9110: read/query verbs map to GET, create/submit to POST, update/modify to PUT or PATCH, and delete/remove to DELETE. Ambiguous cases default to POST with a low-confidence annotation flagged for human review.

What input format does contract generation require?▼

The input must be a use case markdown artifact with YAML frontmatter where work_type is USE_CASE, realization_level is INTERACTION_DEFINED, and the interactions array contains entries with id, source_step, source_flow, actor_role, system_role, request_description, and response_description.

Can this skill generate AsyncAPI or CloudEvents specifications?▼

No. AsyncAPI and CloudEvents generation is deferred in version 1.0.0 because multi-actor publish/subscribe mapping is unresolved. Templates exist as scaffolding only, and the generator explicitly refuses to produce these contract types.

Why does the generated contract have an x-prototype label?▼

All generated contracts carry x-prototype: true because the UC-to-contract algorithm is novel and requires human review before production use. The label is removed only after the validator passes all 9 checks and a reviewer completes the 8-item sign-off checklist.

What happens if my use case artifact has no interactions block?▼

Generation is rejected with an actionable message directing you to run the use-case skill's uc-slicer Activity 5 first. The transformation requires at least one interaction entry and will not attempt to generate contracts from incomplete input.

Related Skills

Explore More Software Engineering Skills→
AppsVortexAppsVortex
31

arn-spark-use-cases

Orchestrate end-to-end use-case authoring for Arness projects with expert reviews.

Official
Advanced
Ankurjain1121Ankurjain1121

openapi-spec-generation

Convert API contracts into OpenAPI 3.1 specifications and SDK templates.

Community
Advanced
hpsgdhpsgd

write-feature-spec

Generate Gherkin feature files and pytest-bdd step definitions from natural-language prompts.

Official
Advanced
paraskakisparaskakis
41

design-api-spec

Generate an OpenAPI 3.1.0 specification from design stories and domain models.

Community
Advanced