api-changelog-versioning
Creates comprehensive API changelogs documenting breaking changes, deprecations, and migration strategies for API consumers. Use when managing API versions, communicating breaking changes, or creating upgrade guides.
80
75%
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-changelog-versioning/skills/api-changelog-versioning/SKILL.mdQuality
Discovery
100%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 well-crafted skill description that clearly defines its scope around API changelog creation with specific capabilities and explicit trigger conditions. It uses third-person voice, includes natural developer-facing keywords, and carves out a distinct niche. The description follows the pattern of good examples in the rubric closely.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'documenting breaking changes, deprecations, and migration strategies' and specifies the audience ('API consumers'). These are concrete, well-defined capabilities. | 3 / 3 |
Completeness | Clearly answers both what ('Creates comprehensive API changelogs documenting breaking changes, deprecations, and migration strategies') and when ('Use when managing API versions, communicating breaking changes, or creating upgrade guides') with explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms users would say: 'API changelogs', 'breaking changes', 'deprecations', 'migration strategies', 'API versions', 'upgrade guides'. Good coverage of terms a developer managing APIs would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | Occupies a clear niche focused specifically on API changelogs and version migration documentation. The combination of 'API changelogs', 'breaking changes', and 'migration strategies' is distinct enough to avoid conflicts with general documentation or changelog skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
50%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 reasonable template-based approach to API changelog documentation with useful structural examples and before/after comparisons. However, it reads more like a documentation style guide than an actionable skill—it lacks specific tooling, validation steps, and concrete execution guidance. The content could be tightened by removing things Claude already knows (like what 'EOL' means or generic best practices) and adding more specific, executable workflows.
Suggestions
Add validation checkpoints to the migration workflow, such as 'Run API contract tests to verify backward compatibility before publishing' or 'Validate changelog against OpenAPI diff output'.
Remove the 'Version Support Policy' definitions (Current/Maintenance/EOL) as Claude already understands these concepts—replace with specific decision criteria for when to apply each status.
Make the skill more actionable by including concrete commands or scripts, e.g., a tool to diff OpenAPI specs and auto-generate changelog entries, or a checklist Claude can verify programmatically.
Trim the 'Best Practices' section which contains generic advice Claude already knows, and instead add guidance on edge cases or common mistakes specific to this task.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient with good use of templates and tables, but some content like the 'Best Practices' bullet list and 'Version Support Policy' definitions are things Claude already knows. The deprecation schedule with specific dates is somewhat time-sensitive without being flagged as such. | 2 / 3 |
Actionability | Provides concrete markdown templates and before/after examples, which is helpful. However, this is fundamentally a documentation template skill—there are no executable commands or scripts, and the migration steps in the template are generic placeholders ('Update SDK', 'Test in staging') rather than specific, actionable guidance Claude can directly apply. | 2 / 3 |
Workflow Clarity | The migration guide template includes numbered steps, but there are no validation checkpoints or feedback loops. For a skill involving API versioning and breaking changes, there should be explicit verification steps (e.g., 'run integration tests before proceeding', 'verify backward compatibility'). The migration steps are listed but lack error recovery guidance. | 2 / 3 |
Progressive Disclosure | Content is organized into clear sections with headers, which is good. However, everything is inline in a single file—the migration guide template, deprecation schedule, and best practices could benefit from being split out or referenced. For a skill of this length (~70 lines of content), it's borderline acceptable but the changelog example takes up significant space that could be referenced separately. | 2 / 3 |
Total | 8 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- secondsky/claude-skills
- Commit
88da5ff
- 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.