api-design-principles

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.

Quality

28%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

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

Quality

Discovery

22%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This description reads more like a marketing tagline or course title than a functional skill description. It lacks concrete actions, explicit trigger conditions, and uses aspirational fluff ('delight developers', 'stand the test of time') instead of specifying what the skill actually does. The mention of REST and GraphQL provides some keyword value but is insufficient to make this a useful skill selector.

Suggestions

Replace aspirational language with concrete actions, e.g., 'Designs REST endpoints, defines GraphQL schemas, generates OpenAPI/Swagger specs, structures request/response payloads, and applies versioning strategies.'

Add an explicit 'Use when...' clause, e.g., 'Use when the user asks about designing APIs, structuring endpoints, choosing between REST and GraphQL, or creating API documentation.'

Include additional natural trigger terms users might say, such as 'endpoints', 'routes', 'HTTP methods', 'API versioning', 'OpenAPI', 'swagger', 'schema design', or 'API best practices'.

Dimension	Reasoning	Score
Specificity	The description uses vague, aspirational language like 'intuitive, scalable, and maintainable' and 'delight developers' without listing any concrete actions. There are no specific capabilities such as 'design endpoints', 'define schemas', 'generate OpenAPI specs', etc.	1 / 3
Completeness	The description vaguely addresses 'what' (API design principles) but provides no 'when' clause or explicit trigger guidance. There is no 'Use when...' statement, which per the rubric should cap completeness at 2, and the 'what' itself is too vague to even reach that level.	1 / 3
Trigger Term Quality	It includes some relevant keywords like 'REST', 'GraphQL', and 'API design' that users might naturally say. However, it misses common variations and related terms like 'endpoints', 'routes', 'schema', 'OpenAPI', 'swagger', 'HTTP methods', or 'API documentation'.	2 / 3
Distinctiveness Conflict Risk	Mentioning both REST and GraphQL provides some specificity, but the broad framing around 'API design principles' could overlap with skills related to backend development, web services, or general software architecture.	2 / 3
	Total	6 / 12 Passed

Implementation

35%

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

This skill is essentially a thin wrapper that defers all substantive content to an external playbook file. The instructions are too abstract to be actionable on their own — they read more like a table of contents than executable guidance. The skill would benefit greatly from including concrete examples, specific patterns, or at least a meaningful summary of the key design principles inline.

Suggestions

Add concrete, actionable content inline — e.g., a REST resource naming convention example, a sample error response schema, or a GraphQL type definition pattern — so the skill is useful without requiring the external playbook.

Replace the vague 4-step workflow with specific guidance: what exactly should be defined in step 1, what choices exist in step 2, and what validation looks like in step 4 (with an example).

Remove or significantly trim the 'Use this skill when' / 'Do not use this skill when' sections, which consume tokens without adding actionable value for Claude.

Include at least one concrete before/after example (e.g., a poorly designed endpoint vs. a well-designed one) to make the guidance tangible.

Dimension	Reasoning	Score
Conciseness	The 'Use this skill when' and 'Do not use this skill when' sections add moderate bloat without providing actionable value to Claude. The core instructions are lean (4 steps), but the surrounding context is padding that Claude doesn't need.	2 / 3
Actionability	The instructions are extremely vague — 'Define consumers, use cases, and constraints' and 'Choose API style and model resources or types' are abstract directions with no concrete examples, code snippets, schemas, or specific guidance. Everything actionable is deferred to an external file.	1 / 3
Workflow Clarity	There is a 4-step sequence that provides a logical ordering, but the steps are too high-level to be truly useful. There are no validation checkpoints, no examples of what 'validate with examples' means concretely, and no feedback loops for error recovery.	2 / 3
Progressive Disclosure	The skill references an external playbook file which is good progressive disclosure, but the SKILL.md itself provides almost no substantive overview content — it's essentially an empty shell pointing elsewhere. A good overview should contain enough actionable content to be useful on its own before deferring to detailed resources.	2 / 3
	Total	7 / 12 Passed

Validation

90%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: sickn33/antigravity-awesome-skills
Commit: d739c8b

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.