api-design-patterns

REST API design with resource naming, pagination, versioning, and OpenAPI spec generation

Quality

73%

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 ./skills/api-design-patterns/SKILL.md

Quality

Content

80%

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

The content is a concise, highly actionable API reference with real code and config examples and no conceptual padding. Its weaker points are the absence of explicit validation/feedback workflows and the lack of progressive disclosure — heavy inline reference material that could be split into separate files.

Suggestions

Add explicit validation checkpoints or feedback loops where a multi-step process exists (e.g. a spec-validate-implement-deprecate sequence for versioning) to raise workflow clarity.

Move the dense reference catalogs (status codes, OpenAPI spec example, pagination formats) into separate reference files linked from a concise overview in SKILL.md to improve progressive disclosure.

Consider a short "Quick start" or decision section at the top so the overview points clearly into the detailed sections.

Dimension	Reasoning	Score
Conciseness	The body is lean — terse tables, compact code blocks, and bullet rules — and assumes Claude's competence without explaining basic REST concepts; not score 2 because there is no padded explanation, only negligible minor re-statements.	3 / 3
Actionability	Concrete, copy-paste-ready guidance throughout: exact URL patterns, a complete HTTP method table, real JSON error/pagination shapes, real header values, and a valid OpenAPI YAML snippet with $ref — matching the fully-executable anchor.	3 / 3
Workflow Clarity	Per-section rules are clear and well-sequenced (e.g. versioning/deprecation flow) but there are no explicit validation checkpoints or feedback loops; not score 3 because the pattern reference lacks the validation/feedback structure the top anchor requires, and not score 1 because guidance is concrete and ordered.	2 / 3
Progressive Disclosure	Sections are well-organized, but the ~170-line body holds substantial reference material (full status-code catalog, HTTP table, OpenAPI spec example, pagination formats) entirely inline with no one-level-deep references or bundle files; not score 3 because no content is split out, and not score 1 because it is sectioned rather than a monolithic wall of text.	2 / 3
	Total	10 / 12 Passed

Description

67%

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 specific and distinct, naming four concrete API-design capabilities in third person without fluff. Its main weakness is the missing "Use when..." trigger guidance and limited coverage of natural user phrasings, which cap completeness and trigger-term quality at 2.

Suggestions

Add an explicit "Use when..." clause, e.g. "Use when designing or documenting REST APIs, defining endpoints, or generating OpenAPI/Swagger specs."

Broaden trigger terms to include natural phrasings users say: "building an API", "endpoints", "API documentation", "Swagger".

Keep the concrete capability list but lead with the trigger context so the "when" is as clear as the "what".

Dimension	Reasoning	Score
Specificity	Names the domain (REST API design) and lists multiple concrete capabilities — "resource naming, pagination, versioning, and OpenAPI spec generation" — matching the multiple-specific-actions anchor; not score 2 because four distinct named actions are comprehensive rather than partial.	3 / 3
Completeness	It clearly states what the skill does but has no "Use when..." clause or equivalent trigger guidance, which per the guidelines caps completeness at 2; not score 1 because the "what" is explicit and not score 3 because "when" is entirely absent.	2 / 3
Trigger Term Quality	Relevant terms ("REST API design", "pagination", "versioning", "OpenAPI") are present but common natural variations a user would say ("endpoints", "building an API", "API documentation", "Swagger") are missing, and "OpenAPI spec generation" leans technical — fitting score 2 rather than full coverage at 3.	2 / 3
Distinctiveness Conflict Risk	"REST API design with resource naming, pagination, versioning, and OpenAPI spec generation" carves a clear niche with distinct sub-capabilities unlikely to trigger the wrong skill; not score 2 because the named concerns differentiate it beyond mere overlap with a generic backend skill.	3 / 3
	Total	10 / 12 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: rohitg00/awesome-claude-code-toolkit
Path: skills/api-design-patterns/SKILL.md
Commit: ebdf1d5

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