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

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

50%

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 and covers scope, but its actionable guidance is abstract and its progressive disclosure is broken: it points to a nonexistent playbook and orphans the actual bundle files. Most dimensions land at a middling 2.

Suggestions

Fix the broken reference: `resources/implementation-playbook.md` does not exist. Point to the real bundle files (references/rest-best-practices.md, references/graphql-schema-design.md, assets/api-design-checklist.md, assets/rest-api-template.py) so they are discoverable.

Add concrete, executable guidance to the Instructions (e.g., an example REST resource route or a GraphQL schema snippet) rather than abstract directives like 'Specify errors, versioning, pagination.'

Tighten the body: remove the duplicated description line and the repeated resource pointer, and trim the generic Limitations boilerplate to improve conciseness.

Dimension	Reasoning	Score
Conciseness	The body is mostly terse, but it repeats the frontmatter description verbatim (including the fluff), duplicates the resource pointer in both Instructions and Resources, and closes with generic Limitations boilerplate that could be tightened.	2 / 3
Actionability	The numbered steps name concrete deliverables (errors, versioning, pagination, auth), providing some concrete guidance, but they are high-level directives with no executable examples, and the playbook that promised 'patterns, checklists, and templates' does not exist.	2 / 3
Workflow Clarity	A four-step sequence is present and step 4 mentions validation ('Validate with examples and review for consistency'), but the validation is a single terminal check with no error-recovery feedback loop, leaving checkpoints implicit.	2 / 3
Progressive Disclosure	Sectioning (Use when / Do not use when / Instructions / Resources) is reasonable, but the only referenced file `resources/implementation-playbook.md` does not exist, while the real bundle files (rest-best-practices.md, graphql-schema-design.md, api-design-checklist.md, rest-api-template.py) are never linked, breaking navigation.	2 / 3
	Total	8 / 12 Passed

Description

65%

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 names a clear domain and strong trigger terms but is padded with over-claims and omits any explicit 'when to use' guidance. It is adequate but not exemplary.

Suggestions

Add an explicit 'Use when...' trigger clause naming concrete scenarios (e.g., 'Use when designing or refactoring REST/GraphQL APIs, reviewing API specs, or setting team API standards') to raise completeness and distinctiveness.

Replace fluff such as 'delight developers and stand the test of time' with concrete actions like 'model resources, design pagination and versioning, define error contracts' to improve specificity.

Dimension	Reasoning	Score
Specificity	The description names the domain ('REST and GraphQL API design principles') and an action ('build... APIs'), but leans on buzzwords like 'intuitive, scalable, and maintainable', 'delight developers', and 'stand the test of time' rather than listing multiple concrete actions as a score-3 anchor would.	2 / 3
Completeness	It clearly states what the skill does ('Master... API design principles to build... APIs') but contains no 'Use when...' clause or equivalent explicit trigger guidance, which per the rubric caps completeness at 2.	2 / 3
Trigger Term Quality	'REST', 'GraphQL', and 'API design' are exactly the natural terms a user would say when they need this skill, giving good coverage of the core triggers.	3 / 3
Distinctiveness Conflict Risk	REST/GraphQL API design is a recognizable niche, but without explicit use-when triggers the broad 'API design principles' framing could still overlap with framework-specific or general coding skills.	2 / 3
	Total	9 / 12 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

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

	Total	15 / 16 Passed

Repository: sickn33/antigravity-awesome-skills
Commit: 2aaaf59

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