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".

Quality

62%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

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.md

Quality

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 skill description with clear trigger guidance and good distinctiveness. Its main weakness is that the capability description is somewhat shallow — it only describes one action (validate) rather than listing specific sub-capabilities like detecting breaking changes, checking compliance, or reporting specific error types. The trigger terms and 'Use when' clause are well-constructed.

Suggestions

Expand the capability list with more specific actions, 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' providing concrete trigger guidance).	3 / 3
Trigger Term Quality	Includes natural keywords users would say: 'validate API schema', 'check OpenAPI spec', 'verify schema', plus mentions 'JSON Schema', 'GraphQL', and 'API schemas and contracts'. Good coverage of terms a user would naturally use.	3 / 3
Distinctiveness Conflict Risk	The combination of API schema validation with specific specification types (OpenAPI, JSON Schema, GraphQL) creates a clear niche that is unlikely to conflict with other skills. The trigger terms are highly specific to this domain.	3 / 3
	Total	11 / 12 Passed

Implementation

35%

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

This skill provides a comprehensive conceptual framework for API schema validation but falls short on actionability — it reads more like a requirements document than an executable guide. The lack of any concrete commands, code snippets, or configuration examples means Claude would need to independently figure out the actual implementation. The workflow is logically sequenced but lacks the validation checkpoints and feedback loops needed for a multi-step process involving potentially destructive schema changes.

Suggestions

Add concrete, executable commands for each 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

Add explicit validation checkpoints with feedback loops, e.g., 'If structural validation fails in step 2, fix syntax errors before proceeding to linting'

Replace prose-based examples with actual input/output pairs showing a sample OpenAPI snippet and the expected validation report output

Dimension	Reasoning	Score
Conciseness	The content is moderately efficient but includes some unnecessary verbosity. The overview paragraph explains what schema validation is (which Claude already knows), and the examples section describes scenarios in prose rather than providing executable commands. However, it avoids extreme padding and stays relatively focused.	2 / 3
Actionability	The skill provides no executable code, no concrete commands, and no copy-paste ready examples. Steps like 'Run structural validation' and 'Apply Spectral linting rules' are described abstractly without showing actual CLI commands (e.g., `spectral lint openapi.yaml`) or configuration snippets. The examples section describes scenarios in prose rather than showing actual inputs/outputs.	1 / 3
Workflow Clarity	The 8-step sequence is logically ordered and covers the validation workflow comprehensively. However, there are no explicit validation checkpoints or feedback loops — step 6 detects breaking changes but doesn't specify what to do if found mid-workflow, and there's no 'stop and fix before proceeding' pattern for critical errors discovered in earlier steps.	2 / 3
Progressive Disclosure	The skill references external files (implementation.md, errors.md, examples.md) which is good structure, but none of these bundle files actually exist (no bundle files provided). The main SKILL.md also contains substantial inline content that could benefit from better separation, and the references cannot be verified as real.	2 / 3
	Total	7 / 12 Passed

Validation

81%

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 — 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

Repository: jeremylongshore/claude-code-plugins-plus-skills
Commit: 3a2d27d

Reviewed: 2 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.