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

Fix and improve this skill with Tessl

tessl review fix ./skills/antigravity-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 thin wrapper that delegates all substantive content to a referenced file (`resources/implementation-playbook.md`) that doesn't exist in the bundle. The inline instructions are too abstract and vague to be actionable — they read more like a table of contents than actual guidance. Without concrete examples, patterns, code snippets, or specific API design rules, this skill provides almost no value to Claude.

Suggestions

Add concrete, actionable API design patterns inline — e.g., specific REST resource naming conventions, HTTP method mappings, example endpoint designs, or GraphQL schema snippets that Claude can directly apply.

Include at least one worked example showing input (a use case description) and output (a concrete API design with endpoints, methods, status codes, etc.).

Expand the four-step workflow with specific sub-steps, decision criteria, and validation checkpoints — e.g., 'Verify all endpoints return appropriate 4xx/5xx error codes' or 'Check that pagination uses cursor-based approach for large collections'.

Either provide the referenced `resources/implementation-playbook.md` bundle file or inline the essential patterns and checklists so the skill is self-contained.

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, schemas, or specific guidance. There are no executable artifacts, no example API designs, no concrete patterns shown inline.	1 / 3
Workflow Clarity	The four numbered steps are high-level abstractions without any specifics, validation checkpoints, or feedback loops. There is no clear sequence of concrete actions — just a vague outline that could apply to almost anything.	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 — it's essentially an empty shell pointing elsewhere.	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 than a functional skill description. It relies heavily on buzzwords ('delight developers', 'stand the test of time') without specifying concrete actions or when the skill should be selected. The lack of a 'Use when...' clause and absence of specific capabilities make it poorly suited for skill selection among many options.

Suggestions

Replace aspirational language with concrete actions, e.g., 'Designs REST endpoints, defines GraphQL schemas, structures request/response payloads, handles versioning, and generates OpenAPI/Swagger specifications.'

Add an explicit 'Use when...' clause, e.g., 'Use when the user asks about API design, endpoint structure, REST conventions, GraphQL schemas, API versioning, or HTTP method selection.'

Include more natural trigger terms users would say, such as 'endpoints', 'routes', 'HTTP methods', 'OpenAPI', 'swagger', 'query', 'mutation', 'pagination', 'API versioning'.

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 partially addresses 'what' (API design principles) but in very vague terms, and completely lacks any 'when' clause or explicit trigger guidance. There is no 'Use when...' or equivalent.	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', 'HTTP methods', or 'query/mutation'.	2 / 3
Distinctiveness Conflict Risk	Mentioning both REST and GraphQL provides some specificity, but 'API design principles' is broad enough to 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: boisenoise/skills-collections
Commit: c45b103

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