api-endpoint-builder

Builds production-ready REST API endpoints with validation, error handling, authentication, and documentation. Follows best practices for security and scalability.

Quality

37%

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

Fix and improve this skill with Tessl

tessl review fix ./skills/api-endpoint-builder/SKILL.md

Quality

Content

42%Scale 1-3

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

This skill provides highly actionable, executable code examples for building REST API endpoints, which is its primary strength. However, it is significantly over-verbose, explaining many concepts Claude already knows (HTTP status codes, CRUD patterns, basic middleware) and packing all content into a single monolithic file. The workflow lacks clear sequencing with validation checkpoints, reading more like a reference document than a step-by-step guide.

Suggestions

Remove the HTTP status codes list, basic CRUD pattern descriptions, and security checklist items that Claude already knows — focus only on project-specific conventions or non-obvious patterns.

Extract reference material (response format templates, documentation template, testing examples, common patterns) into separate bundle files and reference them from the main SKILL.md.

Add a clear sequential workflow: e.g., '1. Define route → 2. Add validation → 3. Implement handler → 4. Add error handling → 5. Verify with test request → 6. Document' with explicit verification steps between stages.

Reduce the main SKILL.md to under 80 lines by keeping only the core pattern (one complete endpoint example) and linking to detailed references for advanced patterns.

Dimension	Reasoning	Score
Conciseness	The skill is extremely verbose at ~200+ lines, explaining many concepts Claude already knows well (HTTP status codes, CRUD patterns, basic Express middleware, pagination, filtering). The HTTP status code list, response format examples, and security checklist are all standard knowledge that don't need to be spelled out. Much of this content is reference material that adds little unique value.	1 / 3
Actionability	The code examples are concrete, executable, and copy-paste ready. The validation middleware, handler implementation, pagination, filtering, testing, and documentation template are all fully functional JavaScript/Express code with specific patterns.	3 / 3
Workflow Clarity	The skill lists the components of an endpoint (route, validation, handler, error handling) but doesn't provide a clear sequential workflow with validation checkpoints. There's no explicit 'build in this order, verify at each step' process. The security checklist is helpful but isn't integrated into a workflow with feedback loops.	2 / 3
Progressive Disclosure	The content is a monolithic wall of text with everything inline. There are no bundle files, yet the skill includes extensive reference material (status codes, CRUD patterns, pagination, filtering, testing, documentation templates) that should be split into separate files. The 'Related Skills' section references other skills but doesn't offload any of the heavy content.	1 / 3
	Total	7 / 12 Passed

Description

32%Scale 1-3

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 identifies a clear domain (REST API development) and lists relevant feature areas, but it lacks a 'Use when...' clause, which is critical for Claude to know when to select this skill. The capabilities listed are more like high-level categories than concrete, specific actions, and the trigger terms miss common user phrasings and technology-specific keywords.

Suggestions

Add an explicit 'Use when...' clause with trigger terms like 'Use when the user asks to create API endpoints, build a REST API, set up routes, or scaffold backend services.'

Include more specific concrete actions such as 'generates CRUD endpoints, creates OpenAPI/Swagger documentation, implements JWT authentication middleware, adds input validation schemas.'

Add common technology variations and file types users might mention, such as 'Express, FastAPI, Django REST, HTTP routes, API design, swagger, .yaml spec files.'

Dimension	Reasoning	Score
Specificity	Names the domain (REST API endpoints) and lists several aspects (validation, error handling, authentication, documentation), but these read more like feature categories than concrete actions. It doesn't specify formats, frameworks, or granular operations like 'generate OpenAPI specs' or 'create CRUD routes'.	2 / 3
Completeness	Describes what the skill does (builds REST API endpoints with various features) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per the rubric, a missing 'Use when' clause caps completeness at 2, and since the 'when' is entirely absent and the 'what' is only moderately detailed, this scores low.	1 / 3
Trigger Term Quality	Includes relevant terms like 'REST API', 'endpoints', 'authentication', and 'validation' that users might mention, but misses common variations such as 'HTTP routes', 'CRUD', 'API design', 'Express', 'FastAPI', 'OpenAPI', or 'swagger'. Coverage of natural user language is incomplete.	2 / 3
Distinctiveness Conflict Risk	The focus on REST API endpoints provides some specificity, but terms like 'validation', 'error handling', 'authentication', and 'documentation' are broad enough to overlap with general backend development, security, or code generation skills.	2 / 3
	Total	7 / 12 Passed

Validation

90%

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 — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: popey/claude-code-skills
Path: skills/api-endpoint-builder/SKILL.md
Commit: a5a6601

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