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.

1.03x

Quality

55%

Does it follow best practices?

Impact

91%

1.03x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/data/02-architect-apidesign/SKILL.md

Quality

Content

31%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 body is rich with executable, copy-paste-ready code patterns, which makes it genuinely actionable. Its two main weaknesses are verbosity from restating well-known API concepts, and broken progressive disclosure: it inlines a large volume of material while pointing to bundle files that do not exist.

Suggestions

Trim the conceptual re-education (HTTP method semantics, status-code recaps, 'Resources are nouns' basics) that Claude already knows; keep only the non-obvious guidance and the code examples to raise conciseness.

Create the referenced bundle files (references/rest-best-practices.md, references/graphql-schema-design.md, references/api-versioning-strategies.md, assets/rest-api-template.py, assets/graphql-schema-template.graphql, assets/api-design-checklist.md, scripts/openapi-generator.py) or remove the dangling references so navigation is not broken.

Move the bulk of the inline code patterns and API reference material into the referenced files, leaving SKILL.md as a concise overview that points one level deep to them.

Dimension	Reasoning	Score
Conciseness	The ~530-line body restates widely-known knowledge ('Resources are nouns, not verbs', HTTP method semantics, 2xx/4xx/5xx status-code recaps, and best-practices lists) that Claude already knows, alongside legitimately useful code; the conceptual padding makes it noticeably verbose rather than lean.	2 / 5
Actionability	Provides mostly executable FastAPI, GraphQL schema, ariadne resolver, and DataLoader code covering common cases, with only minor gaps such as undefined helper functions (build_query, fetch_users, hash_password) and missing imports (Any, ValidationError).	4 / 5
Workflow Clarity	A two-step 'Interactive Design Process' (Clarify Requirements, Feedback Loop) gives a rough sequence, but there are no validation checkpoints or error-recovery loops; the steps are listed with checkpoints missing or only implicit.	3 / 5
Progressive Disclosure	The Resources section signals seven bundle files (references/, assets/, scripts/), but none of those directories or files actually exist alongside SKILL.md, so the references are dangling; meanwhile ~530 lines of material that belongs in those separate files is inlined, mirroring the 'inlined content that should be separate' anchor.	2 / 5
	Total	11 / 20 Passed

Description

78%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 is well-formed with an explicit 'what' and 'when' and solid trigger phrases, making it strongly usable. Its main weakness is the slightly abstract lead ('Master...principles') rather than crisp concrete capabilities, which keeps specificity from the top anchor.

Dimension	Reasoning	Score
Specificity	Names the domain ('REST and GraphQL API design principles') and concrete actions ('designing new APIs, reviewing API specifications, establishing API design standards'), but the lead verb 'Master...principles' is abstract rather than a specific actionable capability, leaving coverage non-comprehensive.	3 / 5
Completeness	Explicitly answers both 'what' (master REST/GraphQL API design principles to build scalable, maintainable APIs) and 'when' ('Use when designing new APIs, reviewing API specifications, or establishing API design standards') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Includes natural phrases users would say ('designing new APIs', 'reviewing API specifications', 'establishing API design standards') plus the technical terms REST/GraphQL, but omits common synonyms like 'endpoints' or 'OpenAPI/Swagger' that a user might naturally mention.	4 / 5
Distinctiveness Conflict Risk	The REST + GraphQL API-design niche is mostly distinct and unlikely to trigger for unrelated skills, though 'API design standards' has minor overlap risk with general software-design or documentation skills.	4 / 5
	Total	16 / 20 Passed

Validation

87%

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

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (534 lines); consider splitting into references/ and linking	Warning
referenced_paths_exist	Referenced path issues: 7 missing	Warning

	Total	14 / 16 Passed

Repository: majiayu000/claude-skill-registry
Path: skills/data/02-architect-apidesign/SKILL.md
Commit: 04324c6

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