api-design

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

Quality

61%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

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

Quality

Content

57%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 well-structured, actionable API design reference with concrete multi-language code examples, but it inlines substantial reference content that belongs in separate bundle files and lacks an explicit validated workflow.

Suggestions

Move bulk reference material (status-code reference, rate-limit tiers, multi-language implementation examples) into files under references/ and link to them from SKILL.md to improve progressive disclosure and token efficiency.

Tighten or relocate well-known HTTP reference data (status codes, method idempotency/safety table) that Claude already knows, keeping only the opinionated guidance inline.

Add an explicit validation feedback loop around the shipping checklist (e.g., "run the checklist; if any box is unchecked, fix and re-check before shipping") to strengthen workflow clarity.

Dimension	Reasoning	Score
Conciseness	Mostly concrete patterns and examples with little concept padding, but inlined reference material Claude already knows (full HTTP status-code list, method idempotency table) could be trimmed or moved to a reference file.	3 / 5
Actionability	Provides concrete, mostly executable code across TypeScript/Next.js, Python/Django, and Go, plus concrete URL/query/SQL examples covering common cases, with minor gaps (undefined helper functions like createUser, writeError, writeJSON).	4 / 5
Workflow Clarity	A checklist ("Before shipping a new endpoint") and a numbered versioning strategy provide some checkpoints, but as a patterns reference it lacks an explicit sequenced workflow with validation feedback loops.	3 / 5
Progressive Disclosure	Well-organized with clear section headers, but all content is inlined in a single ~520-line file with no external references, and reference material (status codes, rate-limit tiers, multi-language implementation examples) that belongs in separate files is kept inline.	3 / 5
	Total	13 / 20 Passed

Description

66%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 scopes a REST API design niche and lists comprehensive concrete sub-areas with natural trigger terms, but it omits any explicit "Use when..." trigger guidance, which caps completeness and slightly weakens distinctiveness.

Suggestions

Add an explicit "Use when..." clause naming trigger phrases (e.g., "Use when designing or reviewing REST APIs, adding endpoints, or handling pagination, error responses, versioning, or rate limiting").

Include natural synonyms and variations users say (e.g., "endpoints", "RESTful", "HTTP API", "API contracts") to broaden trigger coverage.

Reframe some topic nouns as concrete actions (e.g., "Design resource naming and URL structure", "Choose status codes and shape error responses") to strengthen specificity.

Dimension	Reasoning	Score
Specificity	Lists seven concrete capability areas ("resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting") for production APIs, giving comprehensive domain coverage, though framed as topics rather than verb-based actions.	4 / 5
Completeness	Has a clear "what" (REST API design patterns including the listed sub-areas for production APIs) but no "Use when..." clause or equivalent explicit trigger guidance, which caps completeness at 3 per the rubric guideline.	3 / 5
Trigger Term Quality	Includes natural terms users say ("REST API", "API", "pagination", "error responses", "versioning", "rate limiting") with good coverage, but lacks synonyms or alternative phrasings like "endpoints", "RESTful", or "HTTP API".	4 / 5
Distinctiveness Conflict Risk	"REST API design patterns ... for production APIs" carves a clear, mostly distinct niche with low conflict risk, though the absence of explicit trigger guidance leaves minor overlap risk with generic backend or HTTP skills.	4 / 5
	Total	15 / 20 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (523 lines); consider splitting into references/ and linking	Warning

	Total	15 / 16 Passed

Repository: ysyecust/everything-claude-code
Path: .agents/skills/api-design/SKILL.md
Commit: a9cbecb

Reviewed: 3 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.