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

80%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/api-designer/SKILL.md

Quality

Content

77%

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

This is a strong, actionable API design skill with clear workflow sequencing, concrete CLI commands, and a comprehensive copy-paste-ready OpenAPI template. Its main weaknesses are the large inline template that could be offloaded to a reference file, some redundant guidance on concepts Claude already knows, and missing bundle files that the reference table points to. Overall it provides excellent practical guidance for API design tasks.

Suggestions

Move the large OpenAPI 3.1 template to a separate bundle file (e.g., templates/openapi-starter.yaml) and reference it from the skill body to improve conciseness and progressive disclosure.

Remove or significantly trim the 'Knowledge Reference' section and MUST/MUST NOT items that restate things Claude already knows (e.g., 'Follow REST principles', 'don't ignore HTTP status code semantics').

Provide the referenced bundle files (references/rest-patterns.md, references/versioning.md, etc.) so the progressive disclosure structure actually functions.

Dimension	Reasoning	Score
Conciseness	The skill is generally well-structured but the large OpenAPI template (~80 lines) is borderline excessive for inline content—it could be referenced from a separate file. The MUST DO/MUST NOT DO lists contain some items Claude would already know (e.g., 'use proper HTTP methods', 'don't ignore HTTP status code semantics'). The Knowledge Reference section at the bottom is a list of concepts Claude already knows and adds no value.	2 / 3
Actionability	The skill provides fully executable, copy-paste-ready OpenAPI 3.1 YAML, a concrete RFC 7807 error response example, specific CLI commands for linting and mocking (`npx @redocly/cli lint`, `npx @stoplight/prism-cli mock`), and a detailed output checklist. Guidance is concrete and specific throughout.	3 / 3
Workflow Clarity	The core workflow is clearly sequenced with six numbered steps, includes an explicit validation checkpoint (lint with redocly before proceeding), a mock-and-verify step, and the output checklist reiterates that validation must pass. The sequence is logical with clear dependencies between steps.	3 / 3
Progressive Disclosure	The reference table with 'Load When' guidance is well-designed for progressive disclosure, but no bundle files are provided, so the referenced files (references/rest-patterns.md, etc.) don't actually exist. The large inline OpenAPI template would be better placed in a referenced file, and the skill is somewhat monolithic at ~150+ lines.	2 / 3
	Total	10 / 12 Passed

Description

82%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This description has strong trigger term coverage and specificity, listing concrete API design activities and relevant keywords that users would naturally use. Its main weakness is that it blends 'what' and 'when' together—it reads primarily as trigger guidance without a clear upfront statement of what the skill actually does (e.g., 'Guides API design and architecture decisions'). Despite this structural issue, the description would perform well in skill selection due to its rich, distinctive terminology.

Suggestions

Add an explicit 'what it does' statement before the trigger clauses, e.g., 'Guides REST and GraphQL API design, generates OpenAPI specifications, and recommends architecture patterns.'

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions: designing REST or GraphQL APIs, creating OpenAPI specifications, planning API architecture, resource modeling, versioning strategies, pagination patterns, error handling standards.	3 / 3
Completeness	The 'when' is well-covered with explicit 'Use when...' and 'Invoke for...' clauses, but the 'what does this do' is only implied through the trigger contexts rather than explicitly stated. The description reads more like a list of triggers than a clear statement of capabilities followed by when to use them.	2 / 3
Trigger Term Quality	Includes strong natural keywords users would say: 'REST', 'GraphQL', 'API', 'OpenAPI', 'versioning', 'pagination', 'error handling', 'resource modeling'. These cover common variations of how users would describe API design tasks.	3 / 3
Distinctiveness Conflict Risk	Clearly scoped to API design and architecture with distinct triggers like REST, GraphQL, OpenAPI, pagination patterns, and versioning strategies. Unlikely to conflict with general coding skills or other domain-specific skills.	3 / 3
	Total	11 / 12 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: Jeffallan/claude-skills
Commit: e8be415

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