api-spec-validator

This skill should be used when the user asks to "validate API spec", "check OpenAPI spec", "lint OAS", "review API specification", "convert RAML to OAS", or mentions validating, checking, or reviewing OpenAPI/OAS/Swagger/RAML specifications against best practices.

Quality

90%

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

Quality

Content

81%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 a well-sequenced, validated workflow and real helper scripts, but it is padded by triple restatement of the same rules. Progressive disclosure is good but would benefit from moving bulk rule/fix detail into reference files.

Suggestions

Consolidate the redundant rule restatements: keep the Validation Rules section authoritative and prune the overlapping Best Practices, Common Issues, and Manual Review Checklist sections to cross-references.

Move the per-rule fix instructions and the full example specs into references/ (e.g. references/fix-instructions.md) and link from SKILL.md, reducing the inlined bulk that currently pushes the body past 480 lines.

Reference the two unused example files (example-missing-schemas.yaml, example-operation-id-readability.yaml) and unused scripts (generate_docs.py, infer_schemas.py) from the body, or remove them from the bundle, so all bundle files are discoverable.

Dimension	Reasoning	Score
Conciseness	The ~480-line body restates the same rules three times (Validation Rules, Fix Instructions, and Best Practices/Common Issues/Manual Review Checklist) and re-inlines the frontmatter's 'When to Use' guidance, adding padding beyond what Claude needs.	3 / 5
Actionability	Provides copy-paste-ready commands (anypoint-cli-v4 validate with --local-ruleset, npm install) and names concrete helper scripts (add_operation_ids.py, improve_operation_ids.py, add_examples.py, etc.) all verified to exist, plus per-rule YAML fix examples.	5 / 5
Workflow Clarity	Sequences a two-pass validation process with an explicit gate ('Only proceed to Pass 2 if Pass 1 succeeds'), a 7-step complete workflow, and feedback loops (fix -> re-run Pass 2 -> iterate until clean) appropriate for this batch operation skill.	5 / 5
Progressive Disclosure	Good section structure with real, mostly-clear references to verified bundle files (2 of 4 references and 6 of 8 scripts are linked), but the bulk rule definitions and fix instructions are inlined in SKILL.md rather than offloaded to reference files.	4 / 5
	Total	17 / 20 Passed

Description

100%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 exemplary: it pairs concrete actions with natural user-facing trigger phrases and explicit 'when to use' guidance, covering OpenAPI/OAS/Swagger/RAML synonyms. The second-person framing ('when the user asks') is borderline but reads as third-person about the user rather than 'you can use this', so no specificity penalty is applied.

Dimension	Reasoning	Score
Specificity	Names the API-spec domain plus multiple concrete actions (validate, check, lint, review, convert RAML to OAS), giving comprehensive coverage of what the skill does.	5 / 5
Completeness	Explicitly answers both what (validate specs against best practices) and when, with an explicit 'This skill should be used when the user asks to...' clause listing concrete trigger phrases.	5 / 5
Trigger Term Quality	Includes natural phrases users would say ('validate API spec', 'check OpenAPI spec', 'lint OAS', 'review API specification', 'convert RAML to OAS') with synonyms across OpenAPI/OAS/Swagger/RAML.	5 / 5
Distinctiveness Conflict Risk	Clear niche of API-spec validation/linting/format-conversion with distinct, domain-specific triggers and minimal overlap risk with other skills.	5 / 5
	Total	20 / 20 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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: mulesoft/mulesoft-dx
Path: .claude/skills/api-spec-validator/SKILL.md
Commit: 4cf0cf6

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.