validating-api-schemas
Validate API schemas against OpenAPI, JSON Schema, and GraphQL specifications. Use when validating API schemas and contracts. Trigger with phrases like "validate API schema", "check OpenAPI spec", or "verify schema".
71
66%
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 ./plugins/api-development/api-schema-validator/skills/validating-api-schemas/SKILL.mdQuality
Discovery
89%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 solid description that clearly defines its niche (API schema validation) and provides explicit trigger guidance with natural user phrases. Its main weakness is that the capability description is somewhat shallow — 'validate' is the only action mentioned, without elaborating on what validation entails (e.g., detecting breaking changes, checking compliance, reporting errors). Overall it performs well for skill selection purposes.
Suggestions
Expand the specificity of actions beyond just 'validate' — e.g., 'Validate API schemas against OpenAPI, JSON Schema, and GraphQL specifications, detect breaking changes, check field type compliance, and report schema errors.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (API schema validation) and mentions specific specifications (OpenAPI, JSON Schema, GraphQL), but the core action is just 'validate' — it doesn't list multiple distinct concrete actions like 'detect breaking changes, check field types, verify required fields'. | 2 / 3 |
Completeness | Clearly answers both 'what' (validate API schemas against OpenAPI, JSON Schema, and GraphQL specifications) and 'when' (explicit 'Use when' clause and 'Trigger with phrases like' providing concrete trigger guidance). | 3 / 3 |
Trigger Term Quality | Includes natural trigger terms users would say: 'validate API schema', 'check OpenAPI spec', 'verify schema', plus mentions specific specs like 'JSON Schema' and 'GraphQL'. Good coverage of natural phrases. | 3 / 3 |
Distinctiveness Conflict Risk | Clearly scoped to API schema validation against specific specification formats (OpenAPI, JSON Schema, GraphQL). This is a well-defined niche unlikely to conflict with general coding, documentation, or other skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
42%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill has good structure and progressive disclosure but critically lacks actionability—it reads more like a requirements document than an executable guide. The instructions describe what to do at a high level without providing any concrete commands, configuration files, or code snippets that Claude could actually execute. The workflow is logically ordered but missing validation checkpoints and feedback loops for error recovery.
Suggestions
Add concrete, executable commands for each instruction step (e.g., `spectral lint openapi.yaml --ruleset .spectral.yaml`, `oasdiff breaking base.yaml revision.yaml`)
Include a minimal but complete `.spectral.yaml` configuration example inline rather than just listing it as an output
Provide at least one concrete input/output example showing an actual schema snippet and the expected validation output
Add explicit validation checkpoints with feedback loops in the workflow (e.g., 'If Spectral reports errors, fix findings and re-run before proceeding to step 6')
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is moderately efficient but includes some unnecessary verbosity, particularly in the overview section and examples section which describe scenarios rather than providing executable guidance. Some explanations (e.g., what breaking changes are) could be trimmed since Claude already knows these concepts. | 2 / 3 |
Actionability | Despite listing many steps, the skill provides no executable code, no concrete commands, and no copy-paste ready examples. Instructions like 'Run structural validation' and 'Apply Spectral linting rules' are descriptive rather than actionable—there are no actual CLI commands, configuration snippets, or scripts provided. The examples section describes scenarios in prose rather than showing concrete inputs and outputs. | 1 / 3 |
Workflow Clarity | The 8-step workflow is sequenced logically and the error handling table adds value, but there are no explicit validation checkpoints or feedback loops within the workflow. For a process involving schema validation (which can fail in many ways), there should be explicit 'if X fails, do Y' branching within the steps rather than just a separate error table. | 2 / 3 |
Progressive Disclosure | The skill effectively uses progressive disclosure with clear references to separate files for implementation details, error patterns, and additional examples. References are one level deep and well-signaled (implementation.md, errors.md, examples.md). The main file serves as a clear overview without being monolithic. | 3 / 3 |
Total | 8 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Commit
c8a915c
- 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.