check-schemas

Detect breaking changes in schema-form.json plugin descriptors; run the schema compatibility checker, interpret findings, and guide fixes.

Quality

80%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

78%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.

A highly actionable, well-sequenced operational reference with executable commands throughout and honest coverage of the checker's limitations. Its main weaknesses are a monolithic structure that inlines reference-grade tables in SKILL.md and the absence of an explicit fix-and-recheck loop.

Suggestions

Move the full breaking-change table and the EE plugin coordinate details into a references/ file (e.g. BREAKING-CHANGES.md and EE-PLUGINS.md), keeping only the most common categories inline with clearly signaled links.

Add an explicit feedback loop after findings: fix the schema, re-run the same command with the same --base, and confirm the report is clean before proceeding.

Trim the external-plugin walkthrough to the essential mvn dependency:copy + unzip sequence and push the ZIP-path caveats into a short reference note.

Dimension	Reasoning	Score
Conciseness	The body is information-dense — executable commands, domain rules Claude cannot know, and repo-specific conventions — with no explanation of concepts Claude already knows. Minor verbosity remains (e.g., the multi-step external-ZIP walkthrough and EE coordinate explanation could be tightened), fitting the 4 anchor rather than 5's 'every token earns its place'.	4 / 5
Actionability	Every section gives copy-paste-ready commands: 'bash .circleci/scripts/schema-compat-check.sh --base 4.11.0', 'node scripts/schema-compatibility/check-schema-compatibility.mjs --old ... --new ... --plugin ...', 'mvn dependency:copy -Dartifact=...:zip', and 'unzip -p ... schemas/schema-form.json', covering the common OSS, EE, and external-repo cases. Fully executable guidance covering common cases matches the 5 anchor.	5 / 5
Workflow Clarity	Sequences are explicit with gating ('Run OSS check first — only proceed to EE check if OSS passes' with && chaining) and checkpoints exist ('always check that the output file is non-empty', 'Expected: 0 FAIL', the error-to-fix table). It falls short of 5 because there is no explicit re-run-after-fix loop, and baseline-resolution caveats are stated but not resolved into a checklist.	4 / 5
Progressive Disclosure	The skill is a single ~240-line SKILL.md with no bundle files; the ~45-row breaking-change table and the EE coordinate tables are inlined despite the body itself noting 'the authoritative source is the fixture suite under scripts/schema-compatibility/test/fixtures/'. That content clearly belongs in a separate reference file, matching the 3 anchor ('content that should be separate is inline') rather than 4's 'most content is appropriately placed'.	3 / 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.

A crisp, action-oriented description with concrete domain-specific triggers, weakened only by the complete absence of a 'when to use this skill' clause. Adding a single trigger sentence would raise it to the top band.

Suggestions

Append a trigger clause such as: 'Use when the user mentions schema-form.json, plugin schemas, breaking changes, backward compatibility, or asks whether a schema change is safe.'

Include common synonyms users might say — 'backward compatibility', 'schema diff', 'schema migration' — to improve natural trigger matching.

Dimension	Reasoning	Score
Specificity	The description lists four concrete, third-person actions — "Detect breaking changes in schema-form.json plugin descriptors", "run the schema compatibility checker", "interpret findings", "guide fixes" — covering the full workflow with no generic filler. This matches the anchor for multiple specific concrete actions with comprehensive coverage rather than the 4 anchor's 'minor gaps in coverage'.	5 / 5
Completeness	The 'what' is explicit and clear, but there is no 'Use when...' clause or equivalent trigger guidance, which the judging guidelines state caps completeness at 3. Not 4 because the 'when' is entirely absent rather than merely imprecise; not 2 because the 'what' is concrete and multi-part.	3 / 5
Trigger Term Quality	Strong domain keywords ("breaking changes", "schema-form.json", "schema compatibility checker") that a user would naturally say, but common synonyms like "backward compatibility", "schema diff", or "schema migration" are absent. Good coverage with a few natural terms missing fits the 4 anchor, not the 5 anchor's comprehensive synonym/extension coverage.	4 / 5
Distinctiveness Conflict Risk	"schema-form.json plugin descriptors" carves out a clear niche with distinct triggers; no other plausible skill would fire on these phrases. Fits the 5 anchor (clear niche, minimal conflict risk) rather than 4's 'minor overlap risk with closely related 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: 9 missing, 9 deeper-than-1-level	Warning

	Total	15 / 16 Passed

Repository: gravitee-io/gravitee-access-management
Path: docs/agent-standards/skills/check-schemas/SKILL.md
Commit: 6bfca2c

Reviewed: 5 days 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.