api-design-principles

Principles and checklists for designing and reviewing REST and GraphQL APIs; use when defining or evaluating API contracts (endpoints/schemas), naming, error models, pagination, versioning, and REST vs. GraphQL trade-offs.

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

71%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.

A well-structured, actionable design/review skill with concrete REST examples and a clean reference split. The main weakness is redundancy between the Example Usage and Implementation Details sections and minor restatement of baseline concepts.

Suggestions

Merge the Example Usage workflow and the Implementation Details > Recommended workflow into a single sequenced section to remove the duplicated requirements→style→modeling→operations→cross-cutting steps.

Trim baseline-knowledge explanations (e.g. "REST: best for resource-oriented APIs, cacheable reads, and simple CRUD") in favor of decision criteria or trade-off triggers Claude would not already infer.

Add a short inline GraphQL query/mutation example mirroring the REST one so both API styles have executable guidance directly in SKILL.md, or explicitly point to the GraphQL reference for the worked example.

Dimension	Reasoning	Score
Conciseness	Mostly efficient, but the "Example Usage" steps 1-4 and "Implementation Details > Recommended workflow" steps 1-5 restate the same design sequence, and lines like "REST: best for resource-oriented APIs, cacheable reads, and simple CRUD" restate baseline knowledge Claude already has.	3 / 5
Actionability	Provides concrete, copy-paste-ready curl commands and JSON request/response payloads covering list-with-pagination, create-with-idempotency, and the error model; the minor gap is that no equivalent GraphQL worked example is inline (delegated to references).	4 / 5
Workflow Clarity	A clearly sequenced design/review workflow (requirements → style → contract → checklist → deliverables) with the review checklist serving as a validation checkpoint, though it lacks an explicit validate-fix-retry feedback loop.	4 / 5
Progressive Disclosure	SKILL.md is a clear overview with well-signaled, one-level-deep references (references/rest.md, references/graphql.md, references/review-checklist.md) that are real, appropriately scoped files; detail is correctly split out and navigation is easy.	5 / 5
	Total	16 / 20 Passed

Description

92%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.

A concise, well-targeted description that pairs a clear capability statement with an explicit "use when" trigger clause listing concrete API-design concerns. It is third-person, specific, and unlikely to misfire.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions—"designing and reviewing REST and GraphQL APIs", "defining or evaluating API contracts (endpoints/schemas), naming, error models, pagination, versioning, and REST vs. GraphQL trade-offs"—with comprehensive coverage of the skill's scope.	5 / 5
Completeness	Explicitly answers both what ("Principles and checklists for designing and reviewing REST and GraphQL APIs") and when ("use when defining or evaluating API contracts...") with concrete trigger phrases.	5 / 5
Trigger Term Quality	Good natural-term coverage ("REST", "GraphQL", "API contracts", "endpoints/schemas", "pagination", "versioning", "error models"), but a few natural synonyms a user might say (e.g. OpenAPI/Swagger, spec, deprecation, filtering/sorting) are absent.	4 / 5
Distinctiveness Conflict Risk	The REST+GraphQL API-design niche with cross-cutting concerns and explicit trade-off framing is a clear, distinct trigger set with minimal conflict risk against unrelated skills.	5 / 5
	Total	19 / 20 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: aipoch/medical-research-skills
Path: scientific-skills/Other/api-design-principles/SKILL.md
Commit: 63c61d3

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