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.

1.56x

Quality

72%

Does it follow best practices?

Impact

100%

1.56x

Average score across 3 eval scenarios

Securityby

Advisory

Suggest reviewing before use

Fix and improve this skill with Tessl

tessl review fix ./docs/agent-standards/skills/check-oas/SKILL.md

Quality

Content

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

Description

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

Validation

100%

Warnings & errors only

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: about 2 months ago

Table of Contents

Discovery Implementation Validation

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.