Use when you need framework-agnostic OpenAPI 3.x guidance — spec structure, metadata and versioning, paths and operations, reusable schemas, security schemes, examples, documentation quality, contract validation (e.g. Spectral), breaking-change awareness, and handoffs to codegen — without choosing Spring Boot, Quarkus, or Micronaut. This should trigger for requests such as Review an OpenAPI; Improve an OpenAPI; Improve API contract; Improve API schema design. Part of Plinth Toolkit
SkillScore87Maintained
Automatic
◆Coding pack
Last verified 8/20/2026
What it changes
Passed 18 of 21 test cases with the skill, and 16 of 21 without it.
Without skill78%
With skill87%
Checks it passed that the model alone missed
The response keeps guidance at the OpenAPI contract layer.
The response avoids generating Spring MVC `@RestController` annotations.
The response asks for user confirmation on the trade-off before making changes.
and 2 more in the full report
4 fixed16 passed either way1 still failing2 broke
Pass-rate lift
+9 pp
Tokens
+5%
Agent turns
0%
Response time
-19%
Model gemini-3.6-flashMeasured 8/20/2026v120 of 23 cases passed with skill · 21 comparable
Tokens, turns and time describe resource use, not a dollar price.
See it in action
One of 4 test cases the skill fixed. Same model, same prompt, with and without the skill.
1 of 4
Prompt
We finished refactoring our OpenAPI 3.0 schema and component references in our repository project. What verification command should be executed before promoting these contract changes?
What was checked, without and with the skill
Checked
Without skill
With skill
The response specifies running `./mvnw clean verify` or `mvn clean verify` prior to promoting changes.
Missed
Passed
case-08 · gemini-3.6-flash · 8/20/2026 · answers are capped and redacted
What's inside
The instructions your model reads when the skill loads.
SKILL.md56 lines2 files
OpenAPI 3.x best practices
Help teams produce maintainable OpenAPI 3.x contracts that stay aligned with HTTP semantics and consumer needs.
What is covered in this Skill?
Document structure: openapi, info, servers, tags, and consistent resource grouping
Path and operation design: parameters, request bodies, response matrices, operationId, status codes
Reusable components (schemas, parameters, responses, security schemes) and examples
Validation and CI: spec linting, breaking-change checks, pre-codegen gates
Security modeling in the contract (schemes, scopes, global vs operation security)
Clear boundaries between contract-first design and runtime implementation concerns
Scope: Contract-first quality only. Focus this skill on OpenAPI design, quality, and governance guidance.
Constraints
Keep recommendations at the OpenAPI layer unless the user explicitly asks for Java framework integration. After editing this repository's XML sources, regenerate skills and verify the build.
MANDATORY: Run ./mvnw compile or mvn compile before proposing Java or Maven changes in the same change set
FRAMEWORK: Keep guidance contract-centric; do not prescribe framework-specific controller wiring or runtime exposure details
FUZZING: Keep fuzzing guidance high-level and contract-focused without linking to external skill identifiers
VERIFY: Run ./mvnw clean verify or mvn clean verify before promoting changes
EDGE CASE: If the user goal is ambiguous, stop and ask a clarifying question before editing files or running project-wide commands
EDGE CASE: If required context, files, credentials, or tools are missing, report the blocker explicitly and ask whether to proceed with setup or fallback guidance
EDGE CASE: If requested changes conflict with project constraints or safety boundaries, explain the conflict and ask for user confirmation on the preferred trade-off
When to use this skill
Review an OpenAPI
Improve an OpenAPI
Improve API contract
Improve API schema design
Validate an OpenAPI spec
Workflow
Read reference and assess project context
Read references/701-technologies-openapi.md and inspect current API/context artifacts before proposing changes.
Use when you need framework-agnostic SQL guidance — schema naming, relational table design, query readability, indexes, transactions, database security, migrations, testing, and monitoring — without choosing Spring Boot, Quarkus, or Micronaut. This should trigger for requests such as Review SQL schema or migrations; Improve SQL query performance and readability; Design relational tables and indexes; Review database transaction, security, or monitoring practices. Part of Plinth Toolkit