api-design-assistant
Design and review APIs with suggestions for endpoints, parameters, return types, and best practices. Use when designing new APIs from requirements, reviewing existing API designs, generating API documentation, or getting implementation guidance. Supports REST APIs with focus on endpoint structure, request/response schemas, authentication, pagination, filtering, versioning, and OpenAPI specifications. Triggers when users ask to design, review, document, or improve APIs.
Install with Tessl CLI
npx tessl i github:ArabelaTso/Skills-4-SE --skill api-design-assistant94
Does it follow best practices?
Validation 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 an excellent skill description that hits all the key criteria. It provides specific concrete actions, comprehensive trigger terms that users would naturally use, explicit 'Use when' and 'Triggers when' clauses, and a clear distinctive focus on API design that minimizes conflict risk with other skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Design and review APIs with suggestions for endpoints, parameters, return types' and further specifies 'endpoint structure, request/response schemas, authentication, pagination, filtering, versioning, and OpenAPI specifications.' | 3 / 3 |
Completeness | Clearly answers both what ('Design and review APIs with suggestions for endpoints, parameters, return types, and best practices') AND when ('Use when designing new APIs from requirements, reviewing existing API designs, generating API documentation, or getting implementation guidance'). Includes explicit 'Use when...' clause and 'Triggers when...' statement. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural terms users would say: 'design', 'review', 'document', 'improve', 'APIs', 'REST APIs', 'OpenAPI', 'endpoints', 'authentication', 'pagination'. These are terms users naturally use when working with API design. | 3 / 3 |
Distinctiveness Conflict Risk | Clear niche focused specifically on API design and review. The specific focus on REST APIs, OpenAPI specifications, and API-specific concerns like pagination and versioning makes it unlikely to conflict with general coding or documentation skills. | 3 / 3 |
Total | 12 / 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 and clear workflows. The main weakness is some verbosity in explaining concepts Claude already understands (REST basics, what resources are). The progressive disclosure is excellent with clear references to supporting materials, and the example workflows effectively demonstrate the complete design process.
Suggestions
Remove explanatory text about basic REST concepts (e.g., 'Resources are nouns, actions are HTTP methods') that Claude already knows
Condense the 'Tips for Effective API Design' section which largely repeats guidance already covered in the workflow steps
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably efficient but includes some unnecessary explanation that Claude would already know (e.g., explaining what resources are, basic REST concepts). The content could be tightened by removing explanatory text like 'Resources are nouns (users, products), actions are HTTP methods' and focusing more on the specific patterns and templates. | 2 / 3 |
Actionability | Provides fully executable code examples (Express.js implementation), concrete endpoint patterns, specific JSON schemas, and copy-paste ready examples. The filtering patterns, endpoint structures, and documentation templates are all directly usable. | 3 / 3 |
Workflow Clarity | Clear multi-step workflows for both new API design (5 steps) and API review (4 steps). Each step is explicitly numbered with clear actions. The example workflows demonstrate the complete process from requirements to implementation. | 3 / 3 |
Progressive Disclosure | Well-structured with clear overview, detailed sections, and appropriate references to external files (best-practices.md, openapi-template.md). References are one level deep and clearly signaled. Content is appropriately split between the main skill and reference materials. | 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.
- 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.