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

Install with Tessl CLI

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

What are skills?

1.04x

Quality

42%

Does it follow best practices?

Impact

88%

1.04x

Average score across 3 eval scenarios

Optimize this skill with Tessl

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

SKILL.md

Review

Evals

Discovery

50%

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 establishes a clear domain (API design for REST and GraphQL) and includes a partial 'Use when' clause, which is positive. However, it relies on vague marketing language ('delight developers', 'Master') rather than concrete actions, and appears truncated which limits its effectiveness. The trigger terms are adequate but could include more natural variations users would actually say.

Suggestions

Replace vague language like 'Master' and 'delight developers' with specific concrete actions such as 'Define RESTful endpoints, design GraphQL schemas, structure error responses, implement pagination patterns'.

Expand trigger terms to include common variations: 'endpoints', 'routes', 'OpenAPI', 'swagger', 'schema', 'API versioning'.

Complete the truncated 'Use when...' clause and ensure it covers the full range of scenarios where this skill applies.

Dimension	Reasoning	Score
Specificity	Names the domain (REST and GraphQL API design) and mentions some actions (designing, reviewing, establishing), but lacks concrete specific actions like 'define endpoints', 'structure responses', or 'version APIs'.	2 / 3
Completeness	Has a 'Use when...' clause that addresses when to use it (designing new APIs, reviewing specifications, establishing...), but the description is truncated and the 'what' portion uses vague language like 'delight developers' rather than concrete capabilities.	2 / 3
Trigger Term Quality	Includes relevant keywords like 'REST', 'GraphQL', 'API design', 'API specifications', but missing common variations users might say like 'endpoints', 'routes', 'schema design', 'OpenAPI', or 'swagger'.	2 / 3
Distinctiveness Conflict Risk	Distinguishes itself by focusing on REST and GraphQL API design specifically, but could overlap with general coding skills or backend development skills; the truncated description limits clarity on its unique niche.	2 / 3
	Total	8 / 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 content is too abstract and defers nearly all actionable guidance to an external file. While it maintains good structure and brevity, it fails to provide any concrete examples, code patterns, or specific API design guidance that Claude could immediately apply. The skill reads more like a table of contents than a useful reference.

Suggestions

Add at least one concrete REST API design example showing resource naming, HTTP methods, and response structure

Include a specific GraphQL schema example demonstrating type definitions and query patterns

Provide concrete error response formats and status code mappings rather than just mentioning 'specify errors'

Add a brief checklist or validation criteria that can be used without referencing the external playbook

Dimension	Reasoning	Score
Conciseness	The skill is relatively brief but includes some unnecessary content like the verbose 'Use this skill when' and 'Do not use this skill when' sections that explain obvious contexts Claude could infer. The actual instructions are lean.	2 / 3
Actionability	The instructions are extremely vague and abstract ('Define consumers, use cases, and constraints', 'Choose API style'). No concrete examples, code snippets, API schemas, or specific patterns are provided - everything is deferred to an external file.	1 / 3
Workflow Clarity	Steps are numbered and sequenced, but they are too high-level to be actionable. No validation checkpoints, no feedback loops, and no concrete guidance on what 'validate with examples' actually means in practice.	2 / 3
Progressive Disclosure	References an external playbook file 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

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

Reviewed: about 23 hours 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.