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.

Quality

60%

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-principles/SKILL.md

Quality

Content

46%Weight 40%Scale 1-5

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

The skill is well-structured with clear use/avoid sections and a logical workflow, but it lacks concrete, executable guidance and its single reference points to a non-existent path while ignoring the real bundle files. This makes it more of a table of contents than an actionable skill.

Suggestions

Replace the broken `resources/implementation-playbook.md` reference with the actual bundle files (references/rest-best-practices.md, references/graphql-schema-design.md, assets/api-design-checklist.md, assets/rest-api-template.py), signaling when to consult each.

Add at least one concrete, copy-pasteable example per Instruction step (e.g., a sample REST resource route or a GraphQL type snippet) so the guidance is executable rather than abstract.

Make the validation step explicit with a checkpoint, such as 'Review the spec against assets/api-design-checklist.md before finalizing' instead of the vague 'Validate with examples and review for consistency.'

Dimension	Reasoning	Score
Conciseness	The body is lean (~30 lines) and does not explain concepts Claude already knows, but it repeats the description sentence (adding 'stand the test of time') and references `resources/implementation-playbook.md` twice (inline and in the Resources section).	4 / 5
Actionability	The four Instructions are high-level hints ('Define consumers, use cases, and constraints', 'Choose API style and model resources or types') with no concrete code, commands, or examples, and the referenced playbook path does not exist in the bundle.	2 / 5
Workflow Clarity	A clear sequence exists (define -> choose -> specify -> validate) and includes a validation step, but the steps are abstract with no checkpoints or feedback loops, and 'Validate with examples and review for consistency' is vague.	3 / 5
Progressive Disclosure	The body references `resources/implementation-playbook.md` which is not present in the bundle, while the actual files (references/rest-best-practices.md, references/graphql-schema-design.md, assets/api-design-checklist.md, assets/rest-api-template.py) are never mentioned, breaking navigation.	2 / 5
	Total	11 / 20 Passed

Description

75%Weight 40%Scale 1-5

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 clearly communicates a focused niche (REST and GraphQL API design) with explicit trigger phrases for when to use it. It is slightly weakened by padded adjectives and over-claims ('delight developers') that add length without specificity.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions (designing new APIs, reviewing API specifications, establishing API design standards), though 'Master REST and GraphQL API design principles' is somewhat abstract and padded with adjectives like 'intuitive, scalable, and maintainable.'	4 / 5
Completeness	Explicitly answers both what (build intuitive, scalable, maintainable APIs) and when ('Use when designing new APIs, reviewing API specifications, or establishing API design standards'), with the 'when' concrete; the 'what' is slightly diluted by fluff like 'delight developers.'	4 / 5
Trigger Term Quality	Natural phrases users would say ('designing new APIs', 'reviewing API specifications', 'establishing API design standards') are present, but it lacks synonyms and concrete signal words like file types or technology-specific variants beyond REST/GraphQL.	4 / 5
Distinctiveness Conflict Risk	The REST/GraphQL API design niche is clearly distinct from implementation-only skills, with explicit triggers that minimize overlap risk; only minor overlap with general software-design skills keeps it below 5.	4 / 5
	Total	16 / 20 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: rmyndharis/antigravity-skills
Path: skills/api-design-principles/SKILL.md
Commit: 3eff4af

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