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

84%

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 overview skill with runnable REST examples, a clearly sequenced design/review workflow, and an appropriately split one-level-deep reference bundle. Its main cost is redundancy: the workflow is effectively written twice and generic trade-off statements duplicate what the references already provide, which inflates token cost without adding guidance.

Suggestions

Merge 'Example Usage' Steps 1-2 and the 'Implementation Details' workflow into a single pass-through (the example currently restates the workflow's requirements and style-choice steps nearly verbatim).

Trim the 'Key Features' section and generic REST-vs-GraphQL trade-off bullets, pointing to references/rest.md and references/graphql.md instead of summarizing their content inline.

Make the checklist feedback loop explicit in Step 4: fix flagged issues and re-run the checklist until it passes before producing the deliverables in outputs/.

Dimension	Reasoning	Score
Conciseness	The body is mostly tight bullets with runnable examples and no basic-concept explainers, but the workflow is presented twice — 'Example Usage' Steps 1-4 restate 'Implementation Details' Steps 1-5 (requirements, style choice, modeling, checklist) — and 'Key Features' plus generic REST-vs-GraphQL trade-off statements ('REST: best for resource-oriented APIs, cacheable reads, and simple CRUD') restate knowledge Claude already has and content already in references/. More than minor trimming is needed, so anchor 3 fits better than 4.	3 / 5
Actionability	Concrete, executable guidance throughout: exact endpoint list, copy-paste curl commands with realistic headers (Idempotency-Key, cursor pagination), and full JSON request/response/error examples. Minor gaps keep it below anchor 5 — no GraphQL query/mutation example in the body (deferred to references) and the deliverable format has no template.	4 / 5
Workflow Clarity	A clear numbered 5-step sequence (requirements → style → modeling → operations → cross-cutting) is mirrored by a worked example, with the review checklist as an explicit validation checkpoint and a defined deliverable format. Not anchor 5 because the error-recovery feedback loop (fix flagged issues, re-run checklist until it passes) is only implicit.	4 / 5
Progressive Disclosure	Verified against the actual bundle: all three referenced files (references/rest.md, references/graphql.md, references/review-checklist.md) exist, are one level deep, and are clearly signaled in both 'Dependencies' and 'Reference guides'. The body stays an overview plus a worked example while the detailed principles and checklist are appropriately split into reference files, matching anchor 5.	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 strong description in third-person voice that states concrete capabilities and pairs them with an explicit, detailed 'use when' clause covering the full API design/review domain. The only weakness is modest synonym coverage (e.g., 'API spec' or 'OpenAPI') in its trigger terms.

Dimension	Reasoning	Score
Specificity	The description lists multiple concrete actions ("designing and reviewing", "defining or evaluating API contracts") with comprehensive coverage of the domain's concerns — naming, error models, pagination, versioning, and style trade-offs — which exceeds the 'minor gaps' threshold of anchor 4.	5 / 5
Completeness	It explicitly answers both: the 'what' ("Principles and checklists for designing and reviewing REST and GraphQL APIs") and the 'when' ("use when defining or evaluating API contracts (endpoints/schemas), naming, error models, pagination, versioning, and REST vs. GraphQL trade-offs") with concrete trigger phrases, matching anchor 5 exactly.	5 / 5
Trigger Term Quality	Natural terms are well covered ("REST", "GraphQL", "API contracts", "endpoints", "schemas", "pagination", "versioning", "trade-offs") but a few common synonyms users would say are missing, such as "spec", "OpenAPI", or "breaking changes". This fits anchor 4 ('good keyword coverage; a few natural terms missing') better than anchor 5's comprehensive synonym coverage.	4 / 5
Distinctiveness Conflict Risk	A clear niche (API design/review for REST and GraphQL) with distinct, well-scoped trigger objects; unlikely to be selected for generic coding or documentation tasks, matching anchor 5's minimal conflict risk.	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: 686e09d

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