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.

1.08x

Quality

78%

Does it follow best practices?

Impact

98%

1.08x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/api-design-assistant/SKILL.md

Quality

Content

67%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is well-structured and actionable with solid reference linkage, but it is verbose and inlines REST fundamentals and detailed examples that Claude already knows or that belong in the reference files.

Suggestions

Trim explanations of REST basics (HTTP method semantics, status code enumerations, pagination types) that Claude already knows; link them to best-practices.md instead of restating inline.

Move the full inline markdown documentation sample and the detailed filtering/pagination example blocks into the reference files, keeping only a compact representative snippet in SKILL.md.

Add explicit validation/review checkpoints to the design and review workflows (e.g., 'Confirm each endpoint maps to a resource', 'Verify status codes are consistent across endpoints') to make the sequence more verifiable.

Dimension	Reasoning	Score
Conciseness	Mostly useful but padded with REST knowledge Claude already knows (HTTP method semantics, status code lists, pagination types) and explanatory asides like 'Resources are nouns (users, products), actions are HTTP methods' that could be trimmed.	3 / 5
Actionability	Provides concrete, executable guidance — a complete Express.js handler, concrete endpoint listings, and specific before/after recommendations like 'Change /getUsers to GET /users' — with only minor template-like gaps.	4 / 5
Workflow Clarity	Clear numbered multi-step workflows for both design (5 steps) and review (4 steps) with concrete actions per step; validation checkpoints are largely implicit rather than explicit, which keeps it just below a 5.	4 / 5
Progressive Disclosure	Two real, one-level-deep reference files (best-practices.md, openapi-template.md) are clearly signaled via markdown links, but a fair amount of material that could live in those references (status code lists, pagination/filtering examples, the full markdown doc sample) is inlined in the body.	4 / 5
	Total	15 / 20 Passed

Description

88%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is strong: it clearly states what the skill does and when to use it, with concrete triggers and a well-scoped REST/API niche. Trigger-term coverage is good but could add a couple of common synonyms.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions across the API lifecycle — 'endpoints, parameters, return types', 'authentication, pagination, filtering, versioning', and 'OpenAPI specifications' — giving comprehensive coverage rather than a single action.	5 / 5
Completeness	Explicitly answers both 'what' ('Design and review APIs with suggestions for endpoints, parameters, return types, and best practices') and 'when' ('Use when designing new APIs... Triggers when users ask to design, review, document, or improve APIs.') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Good natural keyword coverage ('design', 'review', 'document', 'improve APIs', 'REST APIs', 'OpenAPI') that users would plausibly say, though a few common synonyms (e.g., 'swagger', 'endpoint') are missing.	4 / 5
Distinctiveness Conflict Risk	Clear niche (REST API design/review) with distinct triggers and a stated focus on endpoint structure and OpenAPI specs; minor overlap risk only with closely related general coding/documentation skills.	4 / 5
	Total	18 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: ArabelaTso/Skills-4-SE
Path: skills/api-design-assistant/SKILL.md
Commit: 4f38503

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

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.