{"id":"4509a8b5-ea83-4d2a-9579-1b4ef3d8cc15","shortId":"vWuSG2","kind":"skill","title":"701-technologies-openapi","tagline":"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 ","description":"# OpenAPI 3.x best practices\n\nHelp teams produce maintainable **OpenAPI 3.x** contracts that stay aligned with HTTP semantics and consumer needs.\n\n**What is covered in this Skill?**\n\n- Document structure: `openapi`, `info`, `servers`, `tags`, and consistent resource grouping\n- Path and operation design: parameters, request bodies, response matrices, `operationId`, status codes\n- Reusable `components` (schemas, parameters, responses, security schemes) and examples\n- Validation and CI: spec linting, breaking-change checks, pre-codegen gates\n- Security modeling in the contract (schemes, scopes, global vs operation security)\n- Clear boundaries between contract-first design and runtime implementation concerns\n\n**Scope:** Contract-first quality only. Focus this skill on OpenAPI design, quality, and governance guidance.\n\n## Constraints\n\nKeep 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.\n\n- **MANDATORY**: Run `./mvnw compile` or `mvn compile` before proposing Java or Maven changes in the same change set\n- **FRAMEWORK**: Keep guidance contract-centric; do not prescribe framework-specific controller wiring or runtime exposure details\n- **FUZZING**: Keep fuzzing guidance high-level and contract-focused without linking to external skill identifiers\n- **MANDATORY**: Regenerate skills with `./mvnw clean install -pl skills-generator` after editing skill or system-prompt XML in this repo\n- **VERIFY**: Run `./mvnw clean verify` or `mvn clean verify` before promoting changes\n- **EDGE CASE**: If the user goal is ambiguous, stop and ask a clarifying question before editing files or running project-wide commands\n- **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\n- **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\n\n## When to use this skill\n\n- Review an OpenAPI\n- Improve an OpenAPI\n- Improve API contract\n- Improve API schema design\n- Validate an OpenAPI spec\n\n## Workflow\n\n1. **Read reference and assess project context**\n\nRead `references/701-technologies-openapi.md` and inspect current API/context artifacts before proposing changes.\n\n2. **Gather scope and decide target improvements**\n\nIdentify requested outcomes, constraints, and the minimum safe set of changes to apply.\n\n3. **Apply technology-aligned changes**\n\nImplement or refactor artifacts following the reference patterns and project conventions.\n\n4. **Run verification and report results**\n\nExecute appropriate checks and summarize what changed, what was verified, and any follow-up actions.\n\n## Reference\n\nFor detailed guidance, examples, and constraints, see [references/701-technologies-openapi.md](references/701-technologies-openapi.md).","tags":["701","technologies","openapi","cursor","rules","java","jabrena","agent-skills","ai-skills","claude","claude-code","claude-code-skills"],"capabilities":["skill","source-jabrena","skill-701-technologies-openapi","topic-agent-skills","topic-ai-skills","topic-claude","topic-claude-code","topic-claude-code-skills","topic-claude-code-subagents","topic-claude-skills","topic-cursor-agent","topic-cursor-ai","topic-cursor-skills","topic-cursorai","topic-github-copilot"],"categories":["cursor-rules-java"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/jabrena/cursor-rules-java/701-technologies-openapi","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add jabrena/cursor-rules-java","source_repo":"https://github.com/jabrena/cursor-rules-java","install_from":"skills.sh"}},"qualityScore":"0.631","qualityRationale":"deterministic score 0.63 from registry signals: · indexed on github topic:agent-skills · 362 github stars · SKILL.md body (2,994 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-26T12:53:39.537Z","embedding":null,"createdAt":"2026-04-18T22:02:30.388Z","updatedAt":"2026-04-26T12:53:39.537Z","lastSeenAt":"2026-04-26T12:53:39.537Z","tsv":"'/mvnw':184,239,259 '1':366 '2':383 '3':13,44,53,403 '4':420 '701':1 'action':441 'agnost':11 'align':58,407 'ambigu':276 'api':355,358 'api/context':378 'appli':402,404 'appropri':427 'artifact':379,412 'ask':164,279,308,333 'assess':370 'awar':38 'best':46 'blocker':305 'bodi':87 'boundari':127,328 'break':36,108 'breaking-chang':35,107 'build':181 'case':270,293,318 'centric':205 'chang':37,109,194,198,268,321,382,400,408,432 'check':110,428 'ci':104 'clarifi':281 'clean':240,260,264 'clear':126 'code':92 'codegen':42,113 'command':291 'compil':185,188 'compon':94 'concern':136 'confirm':336 'conflict':322,331 'consist':78 'constraint':153,325,393,448 'consum':63 'context':296,372 'contract':31,55,119,130,139,204,227,356 'contract-centr':203 'contract-first':129,138 'contract-focus':226 'control':212 'convent':419 'cover':67 'credenti':298 'current':377 'decid':387 'design':84,132,148,360 'detail':217,444 'document':29,71 'e.g':33 'edg':269,292,317 'edit':170,247,284 'exampl':28,101,446 'execut':426 'explain':329 'explicit':163,306 'exposur':216 'extern':232 'fallback':315 'file':285,297 'first':131,140 'focus':143,228 'follow':413,439 'follow-up':438 'framework':10,167,200,210 'framework-agnost':9 'framework-specif':209 'fuzz':218,220 'gate':114 'gather':384 'generat':245 'global':122 'goal':274 'govern':151 'group':80 'guidanc':15,152,202,221,316,445 'handoff':40 'help':48 'high':223 'high-level':222 'http':60 'identifi':234,390 'implement':135,409 'improv':351,354,357,389 'info':74 'inspect':376 'instal':241 'integr':168 'java':166,191 'keep':154,201,219 'layer':159 'level':224 'link':230 'lint':106 'maintain':51 'mandatori':182,235 'matric':89 'maven':193 'metadata':18 'minimum':396 'miss':302 'model':116 'mvn':187,263 'need':8,64 'openapi':4,12,43,52,73,147,158,350,353,363 'oper':23,83,124 'operationid':90 'outcom':392 'paramet':85,96 'path':21,81 'pattern':416 'pl':242 'practic':47 'pre':112 'pre-codegen':111 'prefer':339 'prescrib':208 'proceed':311 'produc':50 'project':289,324,371,418 'project-wid':288 'promot':267 'prompt':252 'propos':190,381 'qualiti':30,141,149 'question':282 'read':367,373 'recommend':155 'refactor':411 'refer':368,415,442 'references/701-technologies-openapi.md':374,450,451 'regener':176,236 'repo':256 'report':303,424 'repositori':172 'request':86,320,391 'requir':295 'resourc':79 'respons':88,97 'result':425 'reusabl':24,93 'review':348 'run':183,258,287,421 'runtim':134,215 'safe':397 'safeti':327 'schema':25,95,359 'scheme':27,99,120 'scope':121,137,385 'secur':26,98,115,125 'see':449 'semant':61 'server':75 'set':199,398 'setup':313 'skill':70,145,177,233,237,244,248,347 'skill-701-technologies-openapi' 'skills-gener':243 'sourc':175 'source-jabrena' 'spec':16,105,364 'specif':211 'spectral':34 'status':91 'stay':57 'stop':277 'structur':17,72 'summar':430 'system':251 'system-prompt':250 'tag':76 'target':388 'team':49 'technolog':3,406 'technologies-openapi':2 'technology-align':405 'tool':300 'topic-agent-skills' 'topic-ai-skills' 'topic-claude' 'topic-claude-code' 'topic-claude-code-skills' 'topic-claude-code-subagents' 'topic-claude-skills' 'topic-cursor-agent' 'topic-cursor-ai' 'topic-cursor-skills' 'topic-cursorai' 'topic-github-copilot' 'trade':341 'trade-off':340 'unless':160 'use':5,345 'user':162,273,335 'valid':32,102,361 'verif':422 'verifi':179,257,261,265,435 'version':20 'vs':123 'whether':309 'wide':290 'wire':213 'without':229 'workflow':365 'x':14,45,54 'xml':174,253","prices":[{"id":"2f9cf0cf-f8c7-4df6-9219-7b122d9a390a","listingId":"4509a8b5-ea83-4d2a-9579-1b4ef3d8cc15","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"jabrena","category":"cursor-rules-java","install_from":"skills.sh"},"createdAt":"2026-04-18T22:02:30.388Z"}],"sources":[{"listingId":"4509a8b5-ea83-4d2a-9579-1b4ef3d8cc15","source":"github","sourceId":"jabrena/cursor-rules-java/701-technologies-openapi","sourceUrl":"https://github.com/jabrena/cursor-rules-java/tree/main/skills/701-technologies-openapi","isPrimary":false,"firstSeenAt":"2026-04-18T22:02:30.388Z","lastSeenAt":"2026-04-26T12:53:39.537Z"}],"details":{"listingId":"4509a8b5-ea83-4d2a-9579-1b4ef3d8cc15","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"jabrena","slug":"701-technologies-openapi","github":{"repo":"jabrena/cursor-rules-java","stars":362,"topics":["agent-skills","ai-skills","claude","claude-code","claude-code-skills","claude-code-subagents","claude-skills","cursor-agent","cursor-ai","cursor-skills","cursorai","github-copilot","intellij-idea","java","prompting","system-prompts"],"license":"apache-2.0","html_url":"https://github.com/jabrena/cursor-rules-java","pushed_at":"2026-04-26T12:50:01Z","description":"A curated and opinionated collection of Skills and Agents to be used in modern SDLC workflows for Java Enterprise development with your favorite AI Agent harness.","skill_md_sha":"eebfb161c773897b9a0a41e52acb62b8ed59083f","skill_md_path":"skills/701-technologies-openapi/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/jabrena/cursor-rules-java/tree/main/skills/701-technologies-openapi"},"layout":"multi","source":"github","category":"cursor-rules-java","frontmatter":{"name":"701-technologies-openapi","license":"Apache-2.0","description":"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 cursor-rules-java project"},"skills_sh_url":"https://skills.sh/jabrena/cursor-rules-java/701-technologies-openapi"},"updatedAt":"2026-04-26T12:53:39.537Z"}}