701-technologies-openapi
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. Part of the skills-for-java project
83
78%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/701-technologies-openapi/SKILL.mdQuality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong description that clearly defines its scope (framework-agnostic OpenAPI 3.x), lists numerous specific capabilities, includes an explicit 'Use when' trigger, and carefully distinguishes itself from framework-specific alternatives. The enumeration of covered topics provides excellent trigger term coverage for developers working with OpenAPI specifications.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions and topics: spec structure, metadata and versioning, paths and operations, reusable schemas, security schemes, examples, documentation quality, contract validation (Spectral), breaking-change awareness, and codegen handoffs. | 3 / 3 |
Completeness | Clearly answers both 'what' (framework-agnostic OpenAPI 3.x guidance covering spec structure, schemas, security, validation, etc.) and 'when' (opens with 'Use when you need framework-agnostic OpenAPI 3.x guidance' and explicitly scopes out Spring Boot, Quarkus, Micronaut). | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'OpenAPI 3.x', 'spec structure', 'schemas', 'security schemes', 'Spectral', 'contract validation', 'breaking-change', 'codegen'. These cover a wide range of terms a developer working with OpenAPI would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive by explicitly scoping to framework-agnostic OpenAPI guidance and explicitly excluding Spring Boot, Quarkus, and Micronaut, which clearly differentiates it from framework-specific API skills in the same project. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
57%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill serves primarily as a table of contents and scope declaration, deferring nearly all substantive guidance to a reference file. While the progressive disclosure is well-handled, the skill itself lacks actionable OpenAPI examples, concrete review checklists, or workflow sequences for its stated purposes (review, improve, validate specs). The build-related constraints are concrete but tangential to the core OpenAPI design domain.
Suggestions
Add at least one concrete example of a well-structured OpenAPI snippet (e.g., a path with proper operationId, status codes, and schema references) to make the skill immediately actionable.
Include a clear step-by-step workflow for the primary use case of reviewing/improving an OpenAPI spec, such as: 1. Lint with Spectral, 2. Check specific quality criteria, 3. Validate breaking changes, 4. Verify output.
Remove the 'What is covered' bullet list and instead use that space for concrete, executable guidance — Claude doesn't need a syllabus, it needs instructions.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The 'What is covered' bullet list is somewhat verbose and describes scope rather than instructing. The constraints section has useful content but mixes repo-specific build commands with design guidance in a way that could be tighter. The introductory sentence explaining the purpose is unnecessary for Claude. | 2 / 3 |
Actionability | The skill provides some concrete commands (e.g., `./mvnw compile`, `./mvnw clean install -pl skills-generator`) but lacks any executable OpenAPI examples, spec snippets, linting commands, or concrete guidance on how to actually review/improve an OpenAPI spec. The core domain guidance is entirely deferred to the reference file. | 2 / 3 |
Workflow Clarity | There are some verification steps mentioned (run compile before proposing changes, run clean verify before promoting), but there's no clear sequenced workflow for the primary task of reviewing or improving an OpenAPI spec. The build-related steps are listed as constraints rather than a coherent workflow with validation checkpoints. | 2 / 3 |
Progressive Disclosure | The skill appropriately keeps the SKILL.md as an overview and clearly signals a single one-level-deep reference file for detailed guidance. The reference link is well-signaled and the content split between overview and detailed reference is appropriate. | 3 / 3 |
Total | 9 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- jabrena/cursor-rules-java
- Commit
81b047f
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.