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

77%

Does it follow best practices?

Impact

91%

1.03x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Fix and improve this skill with Tessl

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

Quality

Content

65%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is highly actionable with concrete, executable REST and GraphQL code examples, but it is verbose and inlines material that should live in the referenced bundle files. The referenced bundle files do not exist, weakening progressive disclosure, and the design workflow lacks explicit validation checkpoints.

Suggestions

Move the large inline templates (GraphQL schema, FastAPI REST patterns) into the referenced assets/ files and keep SKILL.md as a concise overview that links to them, so the body is not a monolithic wall of code.

Actually create the referenced bundle files (references/rest-best-practices.md, assets/rest-api-template.py, scripts/openapi-generator.py, etc.) or remove the Resources entries, since the directories do not exist.

Tighten or remove content Claude already knows (HTTP method semantics table, 'Resources are nouns not verbs') to improve token efficiency, and add an explicit validation/review checkpoint to the Interactive Design Process workflow.

Dimension	Reasoning	Score
Conciseness	The body is ~530 lines with extensive inline code and restates basics Claude already knows (HTTP method semantics, 'Resources are nouns not verbs'). It is mostly efficient and concrete but could be tightened and drops some redundant explanation, so it sits at level 2 rather than the lean level-3 anchor or the padded level-1 anchor.	2 / 3
Actionability	It provides concrete, copy-paste-ready FastAPI endpoints, Pydantic models, a full GraphQL schema, resolvers, and DataLoader implementations. It is not level 2 because the code is real and specific rather than pseudocode, though data-access helpers (fetch_users, hash_password, etc.) are intentionally abstracted.	3 / 3
Workflow Clarity	The 'Interactive Design Process' lists Clarify Requirements and a Feedback Loop, giving a light sequence, but there are no explicit validation checkpoints for the design process. It is not level 3 (no checkpoints/feedback-recovery steps) and clears level 2 by having a recognizable sequence.	2 / 3
Progressive Disclosure	The body is organized into clear sections and signals a Resources list, but it inlines large template content (full GraphQL schema, FastAPI patterns) that the Resources section also claims as separate files — and those references/, assets/, and scripts/ directories do not exist. It is not level 3 (references are broken/missing and content that should be split is inline) and not level 1 because structure and signaling are present.	2 / 3
	Total	9 / 12 Passed

Description

90%

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 strong: it states both what the skill does and when to use it with explicit, natural trigger terms in a clear niche. Its only weakness is mild buzzword padding ('delight developers', 'scalable, maintainable') in the capability clause that keeps specificity at 2.

Dimension	Reasoning	Score
Specificity	It names the domain ('REST and GraphQL API design principles') and an action ('build intuitive, scalable, and maintainable APIs'), but the actions are abstract and padded with buzzwords like 'delight developers' rather than listing multiple concrete actions. It is not the level-3 'multiple specific concrete actions' anchor, and it clears level 2 by naming domain plus some actions.	2 / 3
Completeness	It explicitly answers both 'what' ('Master REST and GraphQL API design principles to build... APIs') and 'when' ('Use when designing new APIs, reviewing API specifications...'). The explicit 'Use when...' clause matches the level-3 anchor, so it is not capped at 2.	3 / 3
Trigger Term Quality	The trigger clause 'Use when designing new APIs, reviewing API specifications, or establishing API design standards' uses natural phrases a user would say ('designing new APIs', 'reviewing API specifications'). It is not level 2 because the terms are concrete and relevant rather than generic or jargon-only.	3 / 3
Distinctiveness Conflict Risk	'REST and GraphQL API design principles' is a clear niche with distinct triggers unlikely to fire for unrelated skills. It is not level 2 because the scope is specific rather than broadly overlapping.	3 / 3
	Total	11 / 12 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
Commit: c16cdab

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