This skill excels as a navigation hub with strong progressive disclosure and concise structure, but it fails to provide any concrete, actionable guidance in the main file itself. The anti-patterns and checklist are too generic to be useful without the sub-files, and there are no code examples, specific commands, or executable patterns. It reads more like a table of contents than a skill.

Suggestions

Add at least one concrete, executable example inline—e.g., a sample REST endpoint definition, a response envelope JSON schema, or a quick decision tree with specific recommendations rather than just 'choose based on context'.

Make the decision checklist actionable by providing brief concrete guidance at each step (e.g., 'If consumers are browser SPAs → consider GraphQL; if mobile + third-party → REST with OpenAPI').

Include a minimal quick-start workflow with a concrete example: e.g., 'For a new REST API: 1. Define resources → 2. Map HTTP methods → 3. Define response envelope (see example below) → 4. Validate with api_validator.py'.

Dimension	Reasoning	Score
Conciseness	The content is lean and well-structured. It avoids explaining what APIs, REST, or GraphQL are—concepts Claude already knows. Every section serves a clear purpose: navigation, decision-making, or anti-pattern avoidance.	3 / 3
Actionability	The SKILL.md itself contains no concrete code, commands, specific examples, or executable guidance. The checklist and anti-patterns are generic advice ('choose API style based on context', 'document thoroughly') rather than actionable instructions. All substance is deferred to sub-files with no inline examples.	1 / 3
Workflow Clarity	The decision checklist provides a reasonable sequence of considerations before designing an API, but it lacks explicit validation checkpoints, feedback loops, or concrete steps for what to do at each stage. It's more of a reminder list than a workflow.	2 / 3
Progressive Disclosure	Excellent content map with clear file descriptions and 'When to Read' guidance. References are one level deep, well-signaled, and the selective reading rule is explicitly stated. Related skills are also clearly linked.	3 / 3
	Total	9 / 12 Passed

Description

47%

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 benefits from good keyword coverage with specific technology names that developers would naturally reference. However, it reads as a list of topics rather than concrete actions, and critically lacks any 'Use when...' guidance to help Claude know when to select this skill. Adding action verbs and explicit trigger conditions would significantly improve its effectiveness.

Suggestions

Add a 'Use when...' clause such as 'Use when the user asks about designing APIs, choosing between REST/GraphQL/tRPC, or needs guidance on API versioning, pagination, or response format decisions.'

Rewrite with action verbs to describe concrete capabilities, e.g., 'Guides API architecture decisions, evaluates tradeoffs between REST, GraphQL, and tRPC, designs pagination strategies, and recommends versioning approaches.'

Consider narrowing scope or adding distinguishing context (e.g., 'for web services' or 'for backend systems') to reduce potential overlap with general architecture skills.

Dimension	Reasoning	Score
Specificity	Names the domain (API design) and lists several specific topics (REST vs GraphQL vs tRPC selection, response formats, versioning, pagination), but these read more like topic areas than concrete actions. No action verbs like 'design', 'evaluate', or 'implement' are used.	2 / 3
Completeness	Describes 'what' at a topic level but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, a missing 'Use when...' clause caps completeness at 2, and the 'what' is also weak (topics rather than actions), warranting a 1.	1 / 3
Trigger Term Quality	Includes strong natural keywords users would say: 'API design', 'REST', 'GraphQL', 'tRPC', 'versioning', 'pagination', 'response formats'. These are terms developers naturally use when seeking API design guidance.	3 / 3
Distinctiveness Conflict Risk	The mention of specific technologies (REST, GraphQL, tRPC) and specific concerns (versioning, pagination) provides some distinctiveness, but 'API design principles' is broad enough to potentially overlap with general backend development or architecture skills.	2 / 3
	Total	8 / 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
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning

	Total	10 / 11 Passed

Reviewed

3 months ago

Table of Contents

Discovery Implementation Validation