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

75%

Does it follow best practices?

Impact

100%

1.56x

Average score across 3 eval scenarios

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

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

Quality

Content

76%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable with executable commands and clear organization, and it respects Claude's competence without padding. Its weak spots are the absence of an explicit validation loop around spec regeneration/commit and the lack of file-based progressive disclosure.

Suggestions

Add an explicit validate→fix→retry checkpoint after regenerating the spec, e.g. 'After committing, re-run oas-staleness-check.sh and oas-compat-check.sh to confirm both exit 0.'

Consider moving the breaking-change categories table and oasdiff-output interpretation into a separate reference file (e.g. references/breaking-changes.md) with a clearly signaled link from the overview.

Dimension	Reasoning	Score
Conciseness	The body is dense and assumes Claude's competence (no explaining what OpenAPI or git concepts are), with most operational detail earning its place; a few sections like the 'First-run note' and the long list of --base examples could be trimmed, keeping it just below the lean anchor at 5.	4 / 5
Actionability	Provides fully executable, copy-paste-ready commands throughout — staleness/compat checks, regen, oasdiff install, baseline resolution, and an error-to-fix table — covering the common cases.	5 / 5
Workflow Clarity	Sequences are present (run check → interpret → fix → regen → commit) but there is no explicit validate-after-regen/re-run-check checkpoint for the destructive act of overwriting and committing the regenerated spec, so per the destructive/batch cap workflow clarity is held at 3.	3 / 5
Progressive Disclosure	Well-organized with a top overview table, clear section headers, and an internal nav link; however no content is split into separate reference files (none exist), so it does not reach the one-level-deep reference structure rewarded at 5.	4 / 5
	Total	16 / 20 Passed

Description

75%Weight 40%Scale 1-5

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 specific, distinct, and actionable, clearly conveying what the skill does. Its main weakness is the missing explicit 'when to use' trigger guidance, which caps completeness.

Suggestions

Add an explicit 'Use when…' clause naming natural triggers, e.g. 'Use when modifying docs/mapi/openapi.yaml or when CI OAS checks fail on breaking changes or a stale spec.'

Include common synonyms such as 'swagger' or 'API spec' alongside 'OAS'/'openapi.yaml' to broaden natural trigger coverage.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions — 'Detect breaking changes', 'check whether the committed spec is stale', 'run the OAS checks', 'interpret findings, and guide fixes' — giving comprehensive coverage of the skill's purpose.	5 / 5
Completeness	The 'what' is clear and specific, but there is no 'Use when…' clause or equivalent explicit trigger guidance, so per the rubric cap completeness stays at 3.	3 / 5
Trigger Term Quality	Good natural keyword coverage ('breaking changes', 'openapi.yaml', 'OAS checks', 'stale'), but missing common synonyms a user might say such as 'swagger' or 'API documentation', so it falls short of the comprehensive-synonym anchor at 5.	4 / 5
Distinctiveness Conflict Risk	Targets a clear niche (breaking changes and staleness of docs/mapi/openapi.yaml) with distinct, specific triggers and minimal overlap risk with other skills.	5 / 5
	Total	17 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
referenced_paths_exist	Referenced path issues: 8 missing	Warning

	Total	15 / 16 Passed

Repository: gravitee-io/gravitee-access-management
Path: docs/agent-standards/skills/check-oas/SKILL.md
Commit: 7022872

Reviewed: 1 day 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.