Name: api-design
Rating: 56.8 (1 reviews)
Author: affaan-m

api-design

REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs.

Quality

66%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

High

Do not use without reviewing

Fix and improve this skill with Tessl

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

The canonical home for this skill is api-design in affaan-m/ECC

Quality

Content

71%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 a highly actionable, well-structured REST API reference with copy-paste-ready code across multiple languages and a useful pre-ship checklist. Its main weaknesses are token inefficiency from restating well-known HTTP references and a lack of progressive disclosure, with all content inlined in one long file.

Suggestions

Trim or condense the HTTP status-code reference and method-semantics table, which largely restate knowledge Claude already has, to recover token budget.

Move the per-language implementation examples (Next.js, Django, Go) into separate reference files under references/ and link to them from a concise inline summary, improving progressive disclosure.

De-duplicate the response-envelope and error-format examples that recur across the Response Format, Pagination, and Rate Limiting sections.

Dimension	Reasoning	Score
Conciseness	Well-organized with no basic-concept prose padding, but it inlines a full HTTP status-code reference and method-semantics table that Claude already knows and repeats envelope/error formats, fitting 'mostly efficient but includes some unnecessary explanation or could be tightened.'	3 / 5
Actionability	Provides fully executable, copy-paste-ready code in TypeScript/Next.js with Zod, Django REST Framework, and Go net/http, plus concrete SQL and HTTP examples that cover the common cases, matching the 'fully executable; specific examples cover the common cases' anchor.	5 / 5
Workflow Clarity	The versioning strategy is a clearly numbered sequence with a deprecation timeline and the 'API Design Checklist' supplies explicit pre-ship verification checkpoints, fitting 'clear sequence with most checkpoints present'; no destructive/batch cap applies.	4 / 5
Progressive Disclosure	Good section headers structure the content, but it is a single monolithic ~510-line SKILL.md with no bundle files and no references to separate files, so content that could be split (per-language implementation examples, detailed reference tables) is inlined.	3 / 5
	Total	15 / 20 Passed

Description

61%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 clearly conveys the skill's domain with a comprehensive, specific topic list and natural trigger terms, but it omits any explicit 'Use when…' guidance, capping its completeness. It is distinct and low-conflict but could be more action-oriented.

Suggestions

Add an explicit 'Use when…' trigger clause (e.g., 'Use when designing or reviewing REST API endpoints, or when the user mentions pagination, rate limiting, versioning, or API error handling').

Reframe the topic list with concrete action verbs (e.g., 'Design resource URLs, select HTTP status codes, paginate and filter collections, and structure error responses') to lift specificity.

Include common natural synonyms ('API endpoints', 'RESTful', 'HTTP') to broaden trigger-term coverage.

Dimension	Reasoning	Score
Specificity	Lists many specific sub-areas ('resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting') but frames them as topics under 'design patterns including' rather than concrete actions, so it sits above the minimal anchor 2 yet below the action-oriented anchor 4.	3 / 5
Completeness	Has a clear 'what' but no 'Use when…' clause or equivalent trigger guidance, which per the rubric caps completeness at 3; this matches the anchor 'Has a clear what but when is missing or only weakly implied.'	3 / 5
Trigger Term Quality	Contains natural developer terms ('pagination', 'rate limiting', 'versioning', 'error responses', 'REST API design') users would actually say, matching the 'good keyword coverage; a few natural terms missing' anchor; lacks variants like 'endpoints', 'RESTful', or 'HTTP'.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear niche ('REST API design patterns … for production APIs') with distinct triggers, leaving only minor overlap risk with broader backend/web-development skills, fitting the 'mostly distinct; minor overlap risk' anchor.	4 / 5
	Total	14 / 20 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (526 lines); consider splitting into references/ and linking	Warning
metadata_version	'metadata.version' is missing	Warning

	Total	14 / 16 Passed

Repository: affaan-m/ECC
Path: .kiro/skills/api-design/SKILL.md
Commit: d8409a4

Reviewed: 1 day 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.