api-design-principles

tessl i github:sickn33/antigravity-awesome-skills --skill api-design-principles

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.

57%

Overall

Validation — 81%

Implementation — 35%

Activation — 67%

SKILL.md

Review

Evals

Validation

81%

Warnings & errors only

Criteria	Description	Result
metadata_version	'metadata' field is not a dictionary	Warning
license_field	'license' field is missing	Warning
body_output_format	No obvious output/return/format terms detected; consider specifying expected outputs	Warning

	Total	13 / 16 Passed

Implementation

35%

This skill content is essentially a thin wrapper that defers nearly all substance to an external playbook file. While it maintains good structure and appropriate references, it fails to provide any concrete, actionable guidance in the main skill file itself. The instructions are too abstract to be useful without the referenced resource.

Suggestions

Add at least one concrete example showing a well-designed REST endpoint or GraphQL type with specific naming conventions and patterns

Include a brief checklist of key design decisions (e.g., 'Use nouns for resources: /users not /getUsers', 'Return 201 for created resources') directly in the skill

Replace the abstract 4-step workflow with specific, actionable guidance or at minimum include expected outputs for each step

Remove or condense the 'Use this skill when' and 'Do not use this skill when' sections as they add little value for Claude

Dimension	Reasoning	Score
Conciseness	The content is relatively brief but includes some unnecessary sections like 'Use this skill when' and 'Do not use this skill when' which explain obvious contexts Claude can infer. The opening sentence restates the description verbatim.	2 / 3
Actionability	The instructions are extremely vague with no concrete examples, code, commands, or specific guidance. 'Define consumers, use cases, and constraints' and 'Choose API style' are abstract directions without actionable details.	1 / 3
Workflow Clarity	Steps are numbered and sequenced, but they lack any validation checkpoints, concrete outputs, or feedback loops. The workflow is essentially a high-level outline that defers all detail to an external file.	2 / 3
Progressive Disclosure	References the external playbook appropriately, but the SKILL.md itself provides almost no substantive content - it's essentially just a pointer to another file with minimal overview value.	2 / 3
	Total	7 / 12 Passed

Activation

67%

The description has a solid structure with an explicit 'Use when' clause that clearly defines trigger scenarios. However, it relies on marketing-style language ('delight developers') rather than concrete capabilities, and could benefit from more specific trigger terms that users naturally use when discussing API design.

Suggestions

Replace vague qualifiers ('intuitive, scalable, maintainable', 'delight developers') with specific actions like 'define endpoints, structure request/response schemas, handle versioning, design error responses'

Add more natural trigger terms users would say: 'endpoints', 'routes', 'OpenAPI', 'swagger', 'API documentation', 'request/response format', 'HTTP methods'

Dimension	Reasoning	Score
Specificity	Names the domain (REST and GraphQL API design) and mentions some actions (designing, reviewing, establishing standards), but uses vague qualifiers like 'intuitive, scalable, and maintainable' and 'delight developers' which are abstract rather than concrete capabilities.	2 / 3
Completeness	Clearly answers both what (API design principles for REST and GraphQL) and when (designing new APIs, reviewing specifications, establishing standards) with an explicit 'Use when' clause containing specific triggers.	3 / 3
Trigger Term Quality	Includes relevant keywords like 'REST', 'GraphQL', 'API design', 'API specifications', but misses common variations users might say such as 'endpoints', 'routes', 'schema', 'OpenAPI', 'swagger', or 'API documentation'.	2 / 3
Distinctiveness Conflict Risk	Reasonably specific to API design but could overlap with general coding skills, backend development skills, or documentation skills. The REST/GraphQL focus helps but 'API specifications' and 'design standards' are somewhat broad.	2 / 3
	Total	9 / 12 Passed

Reviewed

16 days ago

Table of Contents

Validation Implementation Activation

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.