Name: api-design
Rating: 68.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. Use when designing or reviewing REST endpoints, resource names, status codes, pagination, or versioning.

Quality

84%

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

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

Quality

Content

77%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.

A highly actionable, concise reference with executable examples and a helpful checklist, but it is delivered as one large inline file rather than split into progressively disclosed reference files.

Suggestions

Split the per-language implementation examples (TypeScript/Python/Go) into a separate references/ file and link to it from SKILL.md to reduce token load and improve progressive disclosure.

Move the detailed status-code and method-semantics reference tables into a bundled reference file, keeping only the most-used subset inline.

Consider extracting the pagination/filtering deep-dive into its own reference with a one-line pointer, since the core skill is endpoint design.

Dimension	Reasoning	Score
Conciseness	The body is mostly lean code examples and tables that assume Claude's familiarity with REST, with only minor explanatory padding (e.g., envelope variant notes) that could be trimmed.	4 / 5
Actionability	Provides copy-paste-ready, executable code across TypeScript, Python, and Go, plus concrete URL examples, status-code tables, and SQL implementations covering the common cases.	5 / 5
Workflow Clarity	Sequenced conceptually with clear 'When to Use Which' guidance and a shipping checklist that acts as a validation checkpoint; no destructive/batch workflow that would require explicit validate-fix-retry loops.	4 / 5
Progressive Disclosure	Sections are well-organized, but the skill is a single monolithic ~515-line file with no bundle files or split-out references, so content that could live in separate files (e.g., per-language implementations) is inlined.	3 / 5
	Total	16 / 20 Passed

Description

91%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.

A strong, well-scoped description that clearly communicates capabilities and explicit activation triggers with comprehensive concrete actions. Minor room to add a few more natural trigger synonyms.

Dimension	Reasoning	Score
Specificity	Lists a comprehensive set of concrete actions—resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting—rather than vague abstractions.	5 / 5
Completeness	Explicitly states both what it does (REST API design patterns) and when to use it ('Use when designing or reviewing REST endpoints...') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Includes natural terms users would say (REST endpoints, resource names, status codes, pagination, versioning), though a few common synonyms or phrasings like 'API design' are absent.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (REST API design) with distinct, specific triggers and minimal overlap risk with unrelated skills.	5 / 5
	Total	19 / 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: affaan-m/ECC
Path: .agents/skills/api-design/SKILL.md
Commit: 5eddf1a

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