CtrlK
BlogDocsLog inGet started
Tessl Logo

rest-api-design

Designs RESTful APIs with proper resource naming, HTTP methods, status codes, and response formats. Use when building new APIs, establishing API conventions, or designing developer-friendly interfaces.

75

Quality

68%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./plugins/rest-api-design/skills/rest-api-design/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Discovery

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.

This is a well-crafted skill description that clearly articulates specific capabilities (resource naming, HTTP methods, status codes, response formats), includes natural trigger terms users would employ, and explicitly states both what the skill does and when to use it. It uses proper third-person voice and is concise without being vague.

DimensionReasoningScore

Specificity

Lists multiple specific concrete actions: 'proper resource naming, HTTP methods, status codes, and response formats' — these are distinct, concrete aspects of API design.

3 / 3

Completeness

Clearly answers both what ('Designs RESTful APIs with proper resource naming, HTTP methods, status codes, and response formats') and when ('Use when building new APIs, establishing API conventions, or designing developer-friendly interfaces') with explicit trigger guidance.

3 / 3

Trigger Term Quality

Includes strong natural keywords users would say: 'RESTful APIs', 'API conventions', 'resource naming', 'HTTP methods', 'status codes', 'developer-friendly interfaces'. These cover common terms a user would use when requesting API design help.

3 / 3

Distinctiveness Conflict Risk

Clearly scoped to RESTful API design specifically — the combination of resource naming, HTTP methods, status codes, and response formats creates a distinct niche unlikely to conflict with general coding or other skills.

3 / 3

Total

12

/

12

Passed

Implementation

37%

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

This skill reads as a REST API cheat sheet covering conventions Claude already knows well (HTTP methods, status codes, resource naming). It lacks a design workflow showing how to apply these conventions when building a new API, and provides no executable implementation code. The content would benefit from focusing on opinionated decisions and project-specific conventions rather than restating widely-known REST standards.

Suggestions

Add a step-by-step workflow for designing an API: e.g., 1) Identify resources, 2) Define relationships, 3) Design endpoints, 4) Define response schemas, 5) Validate with OpenAPI spec

Remove or drastically condense the HTTP methods and status codes tables since Claude already knows these; focus instead on opinionated choices (e.g., when to use PUT vs PATCH, when 422 vs 400)

Add executable code examples showing how to implement these patterns in at least one framework (e.g., Express, FastAPI) to make the skill actionable

Include an error response format example and guidance on consistent error handling, which is a common pain point in API design

DimensionReasoningScore

Conciseness

The content is mostly efficient with good use of tables and examples, but includes information Claude already knows well (HTTP methods, status codes, basic REST conventions). This is essentially a reference card for widely-known REST standards rather than novel guidance.

2 / 3

Actionability

Provides concrete examples of URL patterns, response formats, and query parameters, but lacks executable code for actually implementing an API (e.g., route handlers, middleware). The examples are illustrative rather than copy-paste ready for building something.

2 / 3

Workflow Clarity

There is no workflow or sequenced process for designing an API. The content is a reference sheet of conventions with no guidance on how to apply them step-by-step when designing a new API, no decision points, and no validation steps.

1 / 3

Progressive Disclosure

The content is reasonably organized with clear section headers, but it's a monolithic file with no references to deeper materials (e.g., authentication patterns, error handling guide, OpenAPI spec examples). Some sections like response format could benefit from linking to more detailed examples.

2 / 3

Total

7

/

12

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository
secondsky/claude-skills
Reviewed

Table of Contents

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.