api-design-assistant
Reviews and designs API contracts — function signatures, REST endpoints, library interfaces — for usability, evolvability, and the principle of least surprise. Use when designing a new public interface, when reviewing an API PR, when the user asks whether a signature is well-designed, or when planning a breaking change.
Install with Tessl CLI
npx tessl i github:santosomar/general-secure-coding-agent-skills --skill api-design-assistant100
Quality
100%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
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 follows best practices. It uses third person voice, provides specific concrete actions with examples, includes a comprehensive 'Use when' clause with multiple trigger scenarios, and establishes a clear niche that distinguishes it from general code review or documentation skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Reviews and designs API contracts', with explicit examples of what constitutes API contracts: 'function signatures, REST endpoints, library interfaces'. Also specifies evaluation criteria: 'usability, evolvability, and the principle of least surprise'. | 3 / 3 |
Completeness | Clearly answers both what ('Reviews and designs API contracts...for usability, evolvability, and the principle of least surprise') AND when with explicit 'Use when' clause covering four distinct scenarios: designing new interfaces, reviewing PRs, evaluating signatures, and planning breaking changes. | 3 / 3 |
Trigger Term Quality | Includes natural keywords users would say: 'API', 'function signatures', 'REST endpoints', 'library interfaces', 'API PR', 'signature', 'breaking change'. These cover common variations of how users discuss API design tasks. | 3 / 3 |
Distinctiveness Conflict Risk | Clear niche focused specifically on API contract design and review. The combination of 'API contracts', 'function signatures', 'REST endpoints', and 'breaking change' creates a distinct trigger profile unlikely to conflict with general code review or documentation skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
100%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is an excellent skill that demonstrates mastery of concise, actionable technical writing. The tables efficiently map problems to solutions, the worked example shows rather than tells, and the output format ensures consistent deliverables. The 'API is a promise to strangers' framing is memorable and the three-question framework provides clear evaluation criteria.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Every section earns its place with dense, actionable tables and examples. No explanation of what APIs are or basic concepts Claude already knows. The worked example is substantial but necessary to demonstrate the review process. | 3 / 3 |
Actionability | Provides concrete code examples (Python function signatures), specific tables mapping smells to fixes, a complete worked example with before/after code, and a structured output format template. Copy-paste ready guidance throughout. | 3 / 3 |
Workflow Clarity | The 'three questions' framework provides clear evaluation sequence. The worked example demonstrates the complete review workflow. The output format section gives explicit structure for deliverables. For an API review skill, this is appropriately clear. | 3 / 3 |
Progressive Disclosure | Well-organized with clear sections (usability smells, evolvability, surprise, worked example, REST checklist, do-nots, output format). Content is appropriately contained in one file given the skill's scope. No unnecessary nesting or monolithic walls of text. | 3 / 3 |
Total | 12 / 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.