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

22%

Does it follow best practices?

Impact

—

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

Content

22%

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 hollow shell — it has a reasonable structure and references an external playbook, but the body content provides almost no actionable guidance. The four instructions are so abstract they could apply to any design task. Without concrete examples, specific patterns, code snippets, or even a brief illustration of good vs. bad API design, Claude gains virtually nothing from this skill that it doesn't already know.

Suggestions

Add concrete, executable examples: show a sample REST resource design (URL structure, HTTP methods, request/response JSON) and a GraphQL schema snippet with query examples.

Expand the workflow steps with specific sub-steps and validation checkpoints — e.g., 'After defining resources, verify: each resource has a noun-based URL, uses correct HTTP verbs, returns appropriate status codes.'

Include at least one 'good vs. bad' comparison for a common API design decision (e.g., naming conventions, error response format, pagination approach) to make the guidance actionable.

Either provide the referenced `resources/implementation-playbook.md` bundle file or inline the most critical patterns and checklists directly in the SKILL.md.

Dimension	Reasoning	Score
Conciseness	The 'Use this skill when' and 'Do not use this skill when' sections are somewhat verbose and contain guidance Claude could infer. The Limitations section is boilerplate. However, the core instructions are brief.	2 / 3
Actionability	The instructions are extremely vague and abstract — 'Define consumers, use cases, and constraints' and 'Choose API style and model resources or types' provide no concrete examples, code snippets, schemas, or specific patterns. The skill describes rather than instructs.	1 / 3
Workflow Clarity	The four-step workflow is too high-level to be useful — each step is a vague directive with no concrete sub-steps, validation checkpoints, or examples of what good output looks like. It essentially says 'design the API' in four abstract phases.	1 / 3
Progressive Disclosure	The skill references `resources/implementation-playbook.md` for detailed patterns, which is a reasonable one-level-deep reference. However, no bundle files are provided, so the referenced file doesn't exist, and the SKILL.md itself contains almost no substantive content to serve as a useful overview.	2 / 3
	Total	6 / 12 Passed

Description

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 API design, endpoint structure, REST conventions, GraphQL queries/mutations, or API documentation.'

Include more natural trigger terms and file/format references users might mention, such as 'OpenAPI', 'Swagger', 'HTTP methods', 'status codes', 'query', 'mutation', 'resolver', '.yaml spec'.

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 like 'endpoints', 'routes', 'schema', 'OpenAPI', 'swagger', '.yaml', 'HTTP methods', or 'query/mutation'.	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

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: d89c349

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