api-designer
tessl install github:jeffallan/claude-skills --skill api-designerUse when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.
Review Score
71%
Validation Score
13/16
Implementation Score
42%
Activation Score
100%
Generated
Validation
Total
13/16Score
Passed| Criteria | Score |
|---|---|
metadata_version | 'metadata' field is not a dictionary |
license_field | 'license' field is missing |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata |
Implementation
Suggestions 4
Score
42%Overall Assessment
This skill provides a reasonable organizational framework for API design with good progressive disclosure through reference files, but critically lacks actionable content. It reads more like a job description than executable guidance - Claude already knows REST principles and OpenAPI concepts, so the skill should focus on concrete patterns, code snippets, and specific examples rather than high-level descriptions.
Suggestions
- Add concrete OpenAPI 3.1 specification snippets showing proper resource modeling, error responses, and pagination patterns that Claude can directly adapt
- Replace the abstract 'Role Definition' section with executable examples of well-designed endpoints (e.g., a complete user resource with CRUD operations)
- Add validation checkpoints to the workflow, such as 'Validate OpenAPI spec with spectral lint' or 'Review against checklist before finalizing'
- Include a concrete error response example following RFC 7807 format rather than just referencing it
| Dimension | Score | Reasoning |
|---|---|---|
Conciseness | 2/3 | The skill contains some unnecessary framing ('Senior API architect with 10+ years of experience') and verbose sections like 'Role Definition' that don't add actionable value. The MUST DO/MUST NOT lists are useful but could be more compact. |
Actionability | 1/3 | The skill lacks concrete, executable examples. No actual OpenAPI spec snippets, no code examples, no specific URI patterns demonstrated. It describes what to do ('Create OpenAPI 3.1 spec') rather than showing how with copy-paste ready content. |
Workflow Clarity | 2/3 | The 5-step core workflow provides a clear sequence but lacks validation checkpoints. There's no guidance on how to verify the API design is correct, no feedback loops for iterating on the specification, and no explicit validation steps. |
Progressive Disclosure | 3/3 | Good structure with a clear reference table pointing to specific topic files (rest-patterns.md, versioning.md, etc.) with explicit 'Load When' guidance. References are one level deep and well-signaled. |
Activation
Score
100%Overall Assessment
This is a well-crafted skill description that clearly defines its scope around API design and specification. It uses appropriate third-person voice, includes explicit 'Use when' and 'Invoke for' trigger clauses, and provides comprehensive coverage of relevant technical terms that developers would naturally use. The description effectively distinguishes itself from general coding or documentation skills.
| Dimension | Score | Reasoning |
|---|---|---|
Specificity | 3/3 | 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'. |
Completeness | 3/3 | Explicitly answers both what (designing APIs, creating specs, planning architecture, various patterns) and when ('Use when...', 'Invoke for...'). The 'Use when' and 'Invoke for' clauses provide clear trigger guidance. |
Trigger Term Quality | 3/3 | Excellent coverage of natural terms users would say: 'REST', 'GraphQL', 'APIs', 'OpenAPI', 'API architecture', 'resource modeling', 'versioning', 'pagination', 'error handling'. These are terms developers naturally use when discussing API design. |
Distinctiveness Conflict Risk | 3/3 | Clear niche focused specifically on API design with distinct triggers like 'REST', 'GraphQL', 'OpenAPI', 'pagination patterns'. Unlikely to conflict with general coding skills or other document-related skills. |