api-designer

Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Failed to scan

The risk profile of this skill

Quality

Content

83%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, highly actionable skill body that pairs an explicit workflow with copy-paste templates and a clean one-level reference table pointing to real bundle files. Its main gap is an implicit rather than explicit validate-fix-retry loop in the workflow.

Suggestions

Make the validation feedback loop explicit (e.g. 'If lint fails: fix the spec, re-run lint, only proceed when it passes') to lift workflow_clarity to 5.

Trim the terminal 'Knowledge Reference' line — it lists domains Claude already knows and adds token cost without actionability.

Optionally move the large inline OpenAPI template into references/openapi.md and keep a minimal starter inline, to further reduce token weight while preserving actionability.

Dimension	Reasoning	Score
Conciseness	Largely efficient — a tight workflow, a constraints table, and copy-paste templates assume Claude's competence without explaining basic concepts; the inline OpenAPI template is sizeable but earns its place, with only minor trimming opportunities (e.g. the Knowledge Reference line).	4 / 5
Actionability	Fully executable: copy-paste OpenAPI 3.1 YAML and an RFC 7807 JSON example, plus concrete lint/mock commands ('npx @redocly/cli lint openapi.yaml', 'npx @stoplight/prism-cli mock openapi.yaml') covering the common cases.	5 / 5
Workflow Clarity	Clear 6-step Core Workflow with explicit validation ('validate before proceeding', the lint step) and a mock/verify checkpoint; falls short of 5 because the validate-fix-retry feedback loop is not spelled out as an explicit loop, and the Output Checklist rather than an embedded loop drives final verification.	4 / 5
Progressive Disclosure	Clear overview with a well-signaled one-level-deep reference table mapping topics to real files in references/ (rest-patterns.md, versioning.md, pagination.md, error-handling.md, openapi.md), each with a 'Load When' column; content appropriately split and easy to navigate.	5 / 5
	Total	18 / 20 Passed

Description

83%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, trigger-rich description that clearly states both capability and invocation conditions using third person. It could be slightly tightened by consolidating the two trigger sentences and listing a few more exhaustive actions to reach the top anchors.

Suggestions

Merge the 'Use when...' and 'Invoke for...' clauses into a single, unified trigger sentence so 'when' guidance is in one place.

Add file-format/extension-equivalent trigger terms (e.g. 'openapi.yaml', 'openapi.json', '.graphql schema') to push trigger_term_quality and distinctiveness toward 5.

Tighten the action list to concrete verbs (e.g. 'generate OpenAPI 3.1 specs, define resource models, design pagination and error contracts') to lift specificity toward 5.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ('designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture' and 'resource modeling, versioning strategies, pagination patterns, error handling standards') with only minor gaps; not a fully exhaustive 5-level enumeration.	4 / 5
Completeness	Has both a 'what' (designing/creating/planning APIs and specs) and an explicit 'when' ('Use when...' / 'Invoke for...'), but the 'when' clause splits triggers across two sentences and could be more tightly unified; solidly above a 3, just below the crisp 5 anchor.	4 / 5
Trigger Term Quality	Comprehensive natural term coverage — 'REST or GraphQL APIs', 'OpenAPI specifications', 'API architecture', 'versioning', 'pagination', 'error handling' — phrases a user would naturally say, with synonyms (REST/GraphQL) included.	5 / 5
Distinctiveness Conflict Risk	Clearly scoped to API design with REST/GraphQL/OpenAPI triggers giving it a distinct niche; minor overlap risk with adjacent skills (e.g. graphql-architect, fastapi-expert) named in metadata, but the description itself is mostly distinct.	4 / 5
	Total	17 / 20 Passed

Validation

100%

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

Validation for skill structure

No warnings or errors.

Repository: Jeffallan/claude-skills
Path: skills/api-designer/SKILL.md
Commit: 882ef55

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