api-versioning
Implements RESTful API design with versioning and request specs. Use when building APIs, adding API endpoints, versioning APIs, or when user mentions REST, JSON API, or API design.
84
77%
Does it follow best practices?
Impact
100%
1.26xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/api-versioning/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 skill description with excellent trigger terms and completeness. The explicit 'Use when...' clause with multiple natural trigger terms makes it easy for Claude to select appropriately. The main weakness is that the capability description could be more specific about concrete actions beyond 'design with versioning and request specs'.
Suggestions
Expand the capabilities section to list more specific actions like 'create endpoints, implement authentication, handle pagination, generate API documentation' to improve specificity.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (RESTful API) and mentions some actions (design, versioning, request specs), but doesn't list comprehensive concrete actions like 'create endpoints, handle authentication, implement pagination, generate documentation'. | 2 / 3 |
Completeness | Clearly answers both what ('Implements RESTful API design with versioning and request specs') and when ('Use when building APIs, adding API endpoints, versioning APIs, or when user mentions REST, JSON API, or API design') with explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Good coverage of natural terms users would say: 'APIs', 'API endpoints', 'versioning APIs', 'REST', 'JSON API', 'API design' - these are terms users would naturally use when needing this skill. | 3 / 3 |
Distinctiveness Conflict Risk | Clear niche focused specifically on RESTful API design with distinct triggers (REST, JSON API, API versioning). Unlikely to conflict with general coding skills or other backend skills due to specific API-focused terminology. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a solid, actionable Rails API versioning guide with excellent executable code examples covering controllers, routes, testing, and authentication. The main weaknesses are its length (could be split into focused reference files) and lack of explicit validation steps in the workflow. The content assumes appropriate Rails knowledge but could be tightened by removing the versioning comparison table since URL path is recommended anyway.
Suggestions
Add validation checkpoints to the workflow, e.g., 'Run `rails routes | grep api` to verify routes are registered correctly' after defining routes
Split authentication and testing sections into separate reference files (AUTH.md, TESTING.md) and link from main skill to reduce monolithic content
Remove or condense the versioning strategies comparison table since URL path is the recommended approach - just state the recommendation directly
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is mostly efficient with good code examples, but includes some unnecessary explanation like the versioning strategies table comparison when URL path is recommended anyway, and the overview statement about 'well-structured APIs' is filler Claude already knows. | 2 / 3 |
Actionability | Excellent executable code throughout - complete controller implementations, routes configuration, request specs, and authentication examples are all copy-paste ready with realistic, working Ruby code. | 3 / 3 |
Workflow Clarity | The workflow checklist at the end provides a sequence, but lacks validation checkpoints. For API implementation, there should be explicit steps to verify routes work (e.g., 'run rails routes | grep api'), test the endpoint before moving on, etc. | 2 / 3 |
Progressive Disclosure | Content is well-organized with clear sections, but this is a monolithic file with ~250 lines that could benefit from splitting authentication, testing, and response formats into separate reference files with links from the main skill. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
Total | 10 / 11 Passed | |
- Repository
- ThibautBaissac/rails_ai_agents
- Commit
15fdeaf
- 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.