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.
Install with Tessl CLI
npx tessl i github:jeffallan/claude-skills --skill api-designerOverall
score
71%
Does it follow best practices?
If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:
npx tessl skill review --optimize ./path/to/skillValidation for skill structure
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 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 | 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 | 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. | 3 / 3 |
Trigger Term Quality | 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. | 3 / 3 |
Distinctiveness Conflict Risk | 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. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
42%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 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 | Reasoning | Score |
|---|---|---|
Conciseness | 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. | 2 / 3 |
Actionability | 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. | 1 / 3 |
Workflow Clarity | 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. | 2 / 3 |
Progressive Disclosure | 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. | 3 / 3 |
Total | 8 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 13 / 16 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_version | 'metadata' field is not a dictionary | Warning |
license_field | 'license' field is missing | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 13 / 16 Passed | |
- 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.