api-designer
Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.
92
83%
Does it follow best practices?
Impact
98%
1.00xAverage score across 6 eval scenarios
Passed
No known issues
Quality
Discovery
82%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 description excels at trigger term coverage and specificity, listing numerous concrete API-related concepts that would help Claude select this skill appropriately. Its main weakness is that it jumps straight into 'when to use' without first clearly stating what the skill does — the 'what' is only implied through the trigger terms. Adding an explicit capability statement would make it more complete.
Suggestions
Add an explicit 'what it does' statement before the trigger clauses, e.g., 'Guides REST and GraphQL API design, generates OpenAPI specifications, and recommends architecture patterns.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: designing REST or GraphQL APIs, creating OpenAPI specifications, planning API architecture, resource modeling, versioning strategies, pagination patterns, error handling standards. | 3 / 3 |
Completeness | The 'when' is well-covered with explicit 'Use when...' and 'Invoke for...' clauses, but the 'what does this do' is only implied through the trigger contexts rather than explicitly stated as capabilities. The description reads more like a list of triggers than a clear statement of what the skill actually does (e.g., 'Guides API design and generates specifications'). | 2 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'REST', 'GraphQL', 'API', 'OpenAPI specifications', 'versioning', 'pagination', 'error handling', 'resource modeling'. These cover common variations of how users would describe API design tasks. | 3 / 3 |
Distinctiveness Conflict Risk | Clearly scoped to API design with distinct triggers like REST, GraphQL, OpenAPI, versioning strategies, and pagination patterns. This is a well-defined niche unlikely to conflict with other skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured API design skill with strong actionability through complete OpenAPI templates and specific CLI commands, clear workflow sequencing with validation checkpoints, and excellent progressive disclosure via the reference table. The main weakness is moderate verbosity — the inline OpenAPI template is lengthy and some constraints restate knowledge Claude already has, and the trailing 'Knowledge Reference' section is pure filler.
Suggestions
Move the full OpenAPI template to a separate reference file (e.g., references/openapi-template.yaml) and keep only a minimal 3-5 line snippet inline to improve conciseness.
Remove the 'Knowledge Reference' section at the bottom — it's a list of concepts Claude already knows and adds no actionable value.
Trim MUST DO/MUST NOT DO lists to only non-obvious, project-specific constraints; items like 'Follow REST principles' and 'Use consistent naming conventions' are too generic to be useful.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient but the OpenAPI template is very long (~80 lines) and could be referenced from a separate file. The MUST DO/MUST NOT DO lists contain some items Claude already knows (e.g., 'Follow REST principles', 'Use consistent naming conventions'). The 'Knowledge Reference' section at the bottom adds no value. | 2 / 3 |
Actionability | Provides fully executable, copy-paste-ready OpenAPI 3.1 YAML, a concrete RFC 7807 error response example, specific CLI commands for linting and mocking (`npx @redocly/cli lint`, `npx @stoplight/prism-cli mock`), and a detailed output checklist. The templates are complete and immediately usable. | 3 / 3 |
Workflow Clarity | The core workflow is clearly sequenced with 6 numbered steps, includes an explicit validation checkpoint (step 4: lint before proceeding), a verification step (step 5: mock and test), and the output checklist reinforces that validation must pass. The feedback loop is implicit but the 'validate before proceeding' pattern is clear. | 3 / 3 |
Progressive Disclosure | Excellent use of a reference table with clear 'Load When' conditions pointing to one-level-deep reference files. The main skill provides a concise overview and actionable templates while deferring detailed topic guidance (pagination, versioning, error handling, etc.) to separate reference documents. | 3 / 3 |
Total | 11 / 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
- jeffallan/claude-skills
- Commit
3d95bb1
- 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.