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

51%

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 ./.agent/skills/api-design-principles/SKILL.md

Quality

Discovery

67%

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 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 APIs that delight developers') with specific capabilities like 'define resource naming, versioning strategies, error handling patterns, pagination approaches'

Add more natural trigger terms users would say: 'endpoints', 'routes', 'OpenAPI', 'Swagger', 'API documentation', 'request/response schemas'

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, 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 design standards' is somewhat broad.	2 / 3
	Total	9 / 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 stub that defers all meaningful content to external files. While it attempts good structure with clear sections and references, it fails to provide any actionable guidance, concrete examples, or executable patterns in the main file. The instructions are too abstract to be useful without the referenced playbook.

Suggestions

Add at least one concrete REST API design example (e.g., resource naming, endpoint structure) and one GraphQL schema example directly in the skill

Replace the abstract 4-step instructions with specific, actionable guidance - e.g., 'Name resources as plural nouns: /users, /orders' with before/after examples

Include a quick-reference checklist of the most critical API design rules that can be applied immediately without consulting external files

Remove or significantly condense the 'Use this skill when' and 'Do not use this skill when' sections - these contexts are obvious

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 but the surrounding content adds padding.	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	There is a 4-step sequence provided, but the steps 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 to external resources are present and one-level deep, but the main skill file is essentially empty of substantive content. The balance is wrong - too much deferred, not enough overview content to be useful standalone.	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: Dokhacgiakhoa/antigravity-ide
Commit: 3395991

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