check-oas
Detect breaking changes in docs/mapi/openapi.yaml and check whether the committed spec is stale; run the OAS checks, interpret findings, and guide fixes.
82
72%
Does it follow best practices?
Impact
100%
1.56xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./docs/agent-standards/skills/check-oas/SKILL.mdQuality
Discovery
67%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description is strong in specificity and distinctiveness, clearly listing concrete actions around OpenAPI spec validation and breaking change detection for a specific file. However, it lacks an explicit 'Use when...' clause, which limits completeness, and could benefit from more natural trigger terms that users might actually say when needing this skill.
Suggestions
Add a 'Use when...' clause, e.g., 'Use when checking for breaking changes in the API spec, validating OpenAPI definitions, or when the user mentions API compatibility or spec staleness.'
Include natural keyword variations such as 'OpenAPI', 'swagger', 'API spec', 'schema validation', 'API breaking changes' to improve trigger term coverage.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: detect breaking changes, check whether the spec is stale, run OAS checks, interpret findings, and guide fixes. These are clear, actionable capabilities. | 3 / 3 |
Completeness | Clearly answers 'what does this do' with specific actions, but lacks an explicit 'Use when...' clause or equivalent trigger guidance. The when is only implied by the nature of the actions described. | 2 / 3 |
Trigger Term Quality | Includes some relevant terms like 'breaking changes', 'openapi.yaml', 'OAS checks', and 'stale spec', but misses common user variations like 'OpenAPI', 'swagger', 'API spec', 'schema validation', or 'API compatibility'. The file path 'docs/mapi/openapi.yaml' is very specific but not a natural search term. | 2 / 3 |
Distinctiveness Conflict Risk | Highly distinctive due to the specific file path 'docs/mapi/openapi.yaml', the focus on breaking changes in OpenAPI specs, and OAS checks. Very unlikely to conflict with other skills. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, highly actionable skill with clear workflows and concrete commands for every scenario. Its main weakness is length — the document packs a lot of reference material (breaking change categories, oasdiff output interpretation, fix strategies) inline that could be split into supporting files. The content is well-organized with tables and clear section headers, making it navigable despite its length.
Suggestions
Consider extracting the 'What counts as a breaking change' table, 'Understanding oasdiff output', and 'How to fix breaking changes' into a separate BREAKING-CHANGES-REFERENCE.md to reduce the main skill's token footprint.
Trim explanatory prose that Claude can infer — e.g., the paragraph explaining that regeneration is deterministic could be reduced to a single sentence noting the sort guarantee.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is mostly efficient and provides useful detail, but includes some explanatory text that Claude wouldn't need (e.g., explaining what oasdiff does, what a breaking change is conceptually). The oasdiff breaking changes table and output explanation sections are somewhat verbose for an audience that can read tool output. | 2 / 3 |
Actionability | Excellent actionability throughout — concrete bash commands for every scenario (CI, local, explicit baseline, direct oasdiff), specific fix strategies mapped to specific error types, and copy-paste ready installation commands for oasdiff on both macOS and Linux. | 3 / 3 |
Workflow Clarity | The two scripts are clearly separated with their own sections, exit codes are explicitly documented, the staleness fix workflow is clear (regenerate → commit), and the breaking-change exemption logic is well-explained. The 'How to fix breaking changes' table provides a clear error→fix mapping that serves as a decision checkpoint. | 3 / 3 |
Progressive Disclosure | The content is well-structured with clear sections and a summary table at the top, but it's a long monolithic document (~150 lines of substantive content) with no references to external files. The oasdiff breaking changes catalog and fix strategies could be split into a separate reference file, and the 'Updating the spec' section could be its own document. | 2 / 3 |
Total | 10 / 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
- gravitee-io/gravitee-access-management
- Commit
9821842
- 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.