designing-apis

Designs REST and GraphQL APIs including endpoints, error handling, versioning, and documentation. Use when creating new APIs, designing endpoints, reviewing API contracts, or when asked about REST, GraphQL, or API patterns.

Quality

88%

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

77%

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

The content is a well-structured, actionable API design reference with concrete templates and a workflow plus validation feedback loop. Its main weaknesses are some basic-knowledge padding (HTTP status codes) and a broken external reference with inline content that would benefit from being split into bundle files.

Suggestions

Remove or condense the HTTP status codes table and basic auth-header examples, which restate knowledge Claude already has, to improve conciseness.

Create the referenced OPENAPI-TEMPLATE.md bundle file (or remove the broken link) and move the detailed response-format and GraphQL schema examples into reference files so the SKILL.md body stays a lean overview.

Tighten the response-format section by keeping only the envelope convention and pointing to a reference for full field-by-field examples.

Dimension	Reasoning	Score
Conciseness	The body is mostly lean templates, tables, and checklists, but the HTTP status codes table ("200 OK", "404 Not Found") and basic auth header examples restate concepts Claude already knows, so it could be tightened.	2 / 3
Actionability	It provides concrete, copy-paste-ready guidance: resource URL patterns, JSON success/error/pagination response envelopes, a GraphQL schema template, and rate-limit header values — fully executable reference material.	3 / 3
Workflow Clarity	A numbered 7-step "API Design Workflow" checklist is followed by a separate "Validation Checklist" with an explicit feedback loop ("If validation fails, return to the relevant design step and address the issues"), matching the clear-sequence-with-validation anchor.	3 / 3
Progressive Disclosure	Sections are clearly headed and the OpenAPI template is signaled via a one-level reference, but no bundle files exist and the referenced OPENAPI-TEMPLATE.md is not present, while detailed response formats and the GraphQL schema remain inline content that could be split out.	2 / 3
	Total	10 / 12 Passed

Description

100%

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 concise, uses third person, lists concrete capabilities, and provides an explicit "Use when" clause with natural trigger terms. It clearly distinguishes itself from other skills and answers both what and when.

Dimension	Reasoning	Score
Specificity	"Designs REST and GraphQL APIs including endpoints, error handling, versioning, and documentation" lists multiple concrete actions (design, error handling, versioning, documentation) in third person, matching the anchor for listing several specific concrete actions.	3 / 3
Completeness	It explicitly answers both what ("Designs REST and GraphQL APIs including endpoints, error handling, versioning, and documentation") and when ("Use when creating new APIs, designing endpoints, reviewing API contracts...") with an explicit "Use when" trigger clause.	3 / 3
Trigger Term Quality	"Use when creating new APIs, designing endpoints, reviewing API contracts, or when asked about REST, GraphQL, or API patterns" covers natural terms a user would actually say (REST, GraphQL, API patterns, creating APIs, reviewing contracts).	3 / 3
Distinctiveness Conflict Risk	The REST/GraphQL API design niche with distinct triggers (API contracts, endpoints, versioning) is unlikely to fire for unrelated skills, matching the clear-niche anchor.	3 / 3
	Total	12 / 12 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
relative_links	Relative link issues: 1 missing	Warning

	Total	15 / 16 Passed

Repository: CloudAI-X/claude-workflow-v2
Path: skills/designing-apis/SKILL.md
Commit: 4c242af

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