api-design

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

1.30x

Quality

66%

Does it follow best practices?

Impact

94%

1.30x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/api-design/SKILL.md

Quality

Discovery

75%

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 excels at listing specific, concrete capabilities with strong natural trigger terms that users would actually search for. Its main weakness is the absence of an explicit 'Use when...' clause, which would help Claude know precisely when to select this skill over related ones. Adding trigger guidance would elevate this from a good description to an excellent one.

Suggestions

Add a 'Use when...' clause such as 'Use when designing REST APIs, choosing HTTP status codes, implementing pagination or filtering, or setting up API versioning and rate limiting.'

Consider adding boundary language to reduce overlap with general backend/API skills, e.g., 'Focuses on design patterns and conventions, not implementation in specific frameworks.'

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions/topics: resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting. These are clearly defined, actionable areas of REST API design.	3 / 3
Completeness	Clearly answers 'what does this do' with the list of REST API design patterns, but lacks an explicit 'Use when...' clause or equivalent trigger guidance, which caps this dimension at 2 per the rubric.	2 / 3
Trigger Term Quality	Includes strong natural keywords users would say: 'REST API', 'resource naming', 'status codes', 'pagination', 'filtering', 'error responses', 'versioning', 'rate limiting', 'production APIs'. These cover a wide range of terms a developer would naturally use.	3 / 3
Distinctiveness Conflict Risk	While 'REST API design patterns' is a reasonably specific niche, it could overlap with general API development skills, backend development skills, or web service skills. The lack of explicit trigger boundaries increases conflict risk somewhat.	2 / 3
	Total	10 / 12 Passed

Implementation

57%

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

This is a thorough and highly actionable REST API design reference with excellent concrete examples, good/bad comparisons, and executable code across multiple languages. Its main weaknesses are its monolithic structure (no progressive disclosure to supporting files) and some verbosity from including full implementation examples in three languages inline. The content would benefit significantly from splitting into a concise overview SKILL.md with references to detailed sub-files.

Suggestions

Split implementation examples (TypeScript, Python, Go) into separate referenced files like IMPLEMENTATIONS.md, keeping only one brief example inline

Move detailed pagination, filtering, and rate limiting sections into separate reference files (e.g., PAGINATION.md, FILTERING.md) with one-line summaries and links in the main SKILL.md

Remove the HTTP methods semantics table (idempotent/safe) as Claude already knows this; keep only the status code reference which has more project-specific value

Add a brief workflow for designing a new endpoint (e.g., 1. Define resource → 2. Choose methods → 3. Define schemas → 4. Validate against checklist) with the checklist as the validation step

Dimension	Reasoning	Score
Conciseness	The skill is comprehensive but includes some content Claude already knows well (HTTP method semantics table, basic auth patterns, what idempotent/safe means). The implementation examples in three languages (TypeScript, Python, Go) add significant length and could be trimmed or moved to separate files. However, most content is reference-quality and not padded with unnecessary prose.	2 / 3
Actionability	The skill provides fully executable code examples across multiple languages, concrete URL patterns with good/bad comparisons, specific status codes with usage context, complete JSON response schemas, and SQL queries for pagination implementations. The checklist at the end is immediately actionable.	3 / 3
Workflow Clarity	The content is primarily a reference guide rather than a multi-step workflow, so sequencing is less critical. However, the versioning strategy section has a clear numbered sequence, and the checklist provides a validation step. The skill lacks explicit feedback loops for API design review processes (e.g., validate OpenAPI spec, test error responses, verify rate limiting works).	2 / 3
Progressive Disclosure	This is a monolithic ~350-line file with no references to supporting files. The three full implementation examples (TypeScript, Python, Go), pagination details, filtering patterns, and auth patterns could each be separate reference files. Everything is inline with no navigation structure beyond section headers.	1 / 3
	Total	8 / 12 Passed

Validation

81%

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 — 9 / 11 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (524 lines); consider splitting into references/ and linking	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	9 / 11 Passed

Repository: affaan-m/everything-claude-code
Commit: 841beea

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