Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →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
.claude/skills/jabrena-701-technologies-openapi/SKILL.md| Test case | Without → With | Effect | Δ tokens | Δ turns |
|---|---|---|---|---|
| case-03 | ✗→✓ | ▲ Improved | -2% | 0% |
| case-04 | ✗→✓ | ▲ Improved | -3% | 0% |
| case-05 | ✗→✓ | ▲ Improved | 22% | 0% |
| case-08 | ✗→✓ | ▲ Improved | -34% | 0% |
| case-06 | ✓→✗ | ▼ Worse | -69% | 0% |
Help teams produce maintainable OpenAPI 3.x contracts that stay aligned with HTTP semantics and consumer needs.
What is covered in this Skill?
openapi, info, servers, tags, and consistent resource groupingoperationId, status codescomponents (schemas, parameters, responses, security schemes) and examplesScope: Contract-first quality only. Focus this skill on OpenAPI design, quality, and governance guidance.
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.
./mvnw compile or mvn compile before proposing Java or Maven changes in the same change set./mvnw clean verify or mvn clean verify before promoting changesRead references/701-technologies-openapi.md and inspect current API/context artifacts before proposing changes.
Identify requested outcomes, constraints, and the minimum safe set of changes to apply.
Implement or refactor artifacts following the reference patterns and project conventions.
Execute appropriate checks and summarize what changed, what was verified, and any follow-up actions.
For detailed guidance, examples, and constraints, see references/701-technologies-openapi.md.
| Case | Status | Duration (ms) | Turns | Tokens | Tool calls | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Without | With | Δ | Without | With | Δ | Without | With | Δ | Without | With | Δ | ||
case-01 | fail→fail | 15,806 | 4,079 | -74% | 1 | 1 | 0% | 2,821 | 798 | -72% | 0 | 0 | — |
case-02 | pass→pass | 5,337 | 7,962 | +49% | 1 | 1 | 0% | 793 | 1,243 | +57% | 0 | 0 | — |
case-03 | fail→pass | 36,992 | 29,692 | -20% | 1 | 1 | 0% | 1,690 | 1,657 | -2% | 0 | 0 | — |
case-04 | fail→pass | 12,821 | 10,884 | -15% | 1 | 1 | 0% | 2,655 | 2,579 | -3% | 0 | 0 | — |
case-05 | fail→pass | 14,574 | 14,176 | -3% | 1 | 1 | 0% | 2,660 | 3,245 | +22% | 0 | 0 | — |
case-06 | pass→fail | 23,023 | 4,607 | -80% | 1 | 1 | 0% | 2,790 | 869 | -69% | 0 | 0 | — |
case-07 | pass→pass | 20,046 | 8,397 | -58% | 1 | 1 | 0% | 3,003 | 1,840 | -39% | 0 | 0 | — |
case-08 | fail→pass | 10,032 | 2,869 | -71% | 1 | 1 | 0% | 1,593 | 1,057 | -34% | 0 | 0 | — |
case-09 | pass→pass | 7,263 | 10,168 | +40% | 1 | 1 | 0% | 1,259 | 2,147 | +71% | 0 | 0 | — |
case-10 | pass→fail | 12,695 | 5,757 | -55% | 1 | 1 | 0% | 2,254 | 1,445 | -36% | 0 | 0 | — |
case-11 | pass→pass | 16,656 | 22,452 | +35% | 1 | 1 | 0% | 3,338 | 4,357 | +31% | 0 | 0 | — |
case-12 | pass→pass | 9,792 | 10,327 | +5% | 1 | 1 | 0% | 1,786 | 2,463 | +38% | 0 | 0 | — |
case-13 | pass→pass | 15,419 | 9,070 | -41% | 1 | 1 | 0% | 2,445 | 1,907 | -22% | 0 | 0 | — |
case-14 | pass→pass | 8,387 | 5,342 | -36% | 1 | 1 | 0% | 1,501 | 1,470 | -2% | 0 | 0 | — |
case-15 | pass→pass | 10,610 | 10,129 | -5% | 1 | 1 | 0% | 1,922 | 2,493 | +30% | 0 | 0 | — |
case-16 | pass→pass | 15,999 | 10,229 | -36% | 1 | 1 | 0% | 2,696 | 2,307 | -14% | 0 | 0 | — |
case-17 | pass→pass | 10,201 | 11,974 | +17% | 1 | 1 | 0% | 1,623 | 2,645 | +63% | 0 | 0 | — |
case-18 | pass→pass | 6,884 | 4,521 | -34% | 1 | 1 | 0% | 1,238 | 1,288 | +4% | 0 | 0 | — |
case-19 | pass→pass | 16,962 | 16,392 | -3% | 1 | 1 | 0% | 2,854 | 3,054 | +7% | 0 | 0 | — |
case-20 | pass→pass | 14,503 | 11,175 | -23% | 1 | 1 | 0% | 2,470 | 2,495 | +1% | 0 | 0 | — |
case-21 | pass→pass | 9,019 | 6,906 | -23% | 1 | 1 | 0% | 1,743 | 1,889 | +8% | 0 | 0 | — |
case-22 | pass→pass | 9,993 | 7,636 | -24% | 1 | 1 | 0% | 1,669 | 1,875 | +12% | 0 | 0 | — |
case-23 | pass→pass | 12,390 | 7,786 | -37% | 1 | 1 | 0% | 2,383 | 2,161 | -9% | 0 | 0 | — |
DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 23 cases were attempted, and 21 counted toward the lift figure. The other 2 produced results that are not comparable between the two arms, so they are excluded from the headline rather than averaged into it. The headline lift of +9 percentage points is the difference between those two pass rates over the 21 comparable cases. 3 cases got worse with the skill loaded, and they are included in that figure.
Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.
Other measured skills in the registry, with their headline benchmark lift.