versioning-apis

Implement API versioning with backward compatibility, deprecation notices, and migration paths. Use when managing API versions and backward compatibility. Trigger with phrases like "version the API", "manage API versions", or "handle API versioning".

Quality

86%

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

72%Weight 40%Scale 1-3

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

The body is well-organized and token-efficient with strong progressive disclosure to real reference files, but its workflow lacks explicit validation feedback loops and the main body offers no executable code, relying on references for concrete examples.

Suggestions

Add at least one small executable code snippet in the body (e.g., a version-router middleware stub or a deprecation-header example) so core guidance is copy-paste ready without opening references.

Insert an explicit validation checkpoint in the Instructions workflow — e.g., after building the compatibility layer, 'run version compatibility tests; if any fail, fix the transform and re-run before proceeding' — to add a validate→fix→retry feedback loop.

Tighten steps 2 and 4, which read descriptively ('Select a versioning strategy based on API consumer patterns'), into more decisive, concrete directives.

Dimension	Reasoning	Score
Conciseness	The body is lean — tight overview, numbered instruction steps, a compact error table — and avoids explaining concepts Claude already knows; every section earns its tokens.	3 / 3
Actionability	Concrete specifics appear (header names like 'Accept: application/vnd.api.v2+json', deprecation headers 'Deprecation: true'/'Sunset: <date>', output paths), but the body contains no executable code blocks — actual code lives only in referenced files, leaving guidance incomplete for copy-paste use.	2 / 3
Workflow Clarity	An 8-step sequence is present and includes verification steps (breaking-change detector, compatibility tests), but lacks explicit validate→fix→retry feedback loops; for a destructive/batch context like API migration the checkpoints remain implicit.	2 / 3
Progressive Disclosure	Clear overview with well-signaled, one-level-deep references to implementation.md, errors.md, and examples.md (all real files in ./references/), with content appropriately split between body and references.	3 / 3
	Total	10 / 12 Passed

Description

100%Weight 40%Scale 1-3

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, complete, and distinct, with concrete actions and natural trigger phrases covering both what the skill does and when to use it. It uses appropriate third-person voice throughout.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'Implement API versioning with backward compatibility, deprecation notices, and migration paths' — matching the top anchor.	3 / 3
Completeness	Clearly answers both what (implement versioning, deprecation, migration) and when via an explicit 'Use when managing API versions and backward compatibility' clause.	3 / 3
Trigger Term Quality	Provides natural phrases users would say — 'version the API', 'manage API versions', 'handle API versioning' — giving good coverage of common variations.	3 / 3
Distinctiveness Conflict Risk	Targets a clear niche (API versioning lifecycle) with distinct triggers unlikely to collide with other skills.	3 / 3
	Total	12 / 12 Passed

Validation

87%

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

Repository: jeremylongshore/claude-code-plugins-plus-skills
Path: plugins/api-development/api-versioning-manager/skills/versioning-apis/SKILL.md
Commit: 0540a62

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.