CtrlK
BlogDocsLog inGet started
Tessl Logo

api-design

REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs.

56

Quality

64%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

High

Do not use without reviewing

Fix and improve this skill with Tessl

tessl review fix ./.kiro/skills/api-design/SKILL.md

The canonical home for this skill is api-design in affaan-m/ECC

SKILL.md
Quality
Evals
Security

Quality

Content

63%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.

The body is a well-structured, highly actionable pattern catalog with excellent GOOD/BAD examples and multi-language implementation code. Its main weaknesses are inlining knowledge Claude already has (HTTP basics) and keeping all ~500 lines monolithic in SKILL.md instead of splitting detailed reference material into separate files.

Suggestions

Move the language-specific implementation examples (TypeScript/Python/Go) and detailed pattern sections into references/ files, keeping SKILL.md as a concise overview with one-level-deep links.

Trim or condense the HTTP method semantics table and status-code reference list, which restate knowledge Claude already has, in favor of project-specific conventions.

Complete the code examples by defining or stubbing helper functions (writeError/writeJSON in Go, createUser in TypeScript) so they are copy-paste executable.

DimensionReasoningScore

Conciseness

The body is well organized with almost no filler prose, but it inlines reference material Claude already knows, such as the HTTP method idempotency/safety table and a full status-code semantics list, which could be trimmed or condensed. Not 4 because this known-knowledge padding is more than 'minor instances of over-explanation'; not 2 because there is no concept-explanation padding and most content is genuinely convention-specific.

3 / 5

Actionability

Provides concrete, mostly executable guidance throughout: exact URL structures, SQL snippets, header examples, GOOD/BAD contrasts, and runnable TypeScript, Python, and Go examples covering common cases. Not 5 because of minor gaps, e.g. the Go example relies on undefined writeError/writeJSON helpers and the TypeScript example on an undefined createUser function.

4 / 5

Workflow Clarity

A 'When to Activate' section and a pre-shipping checklist give a clear consult-then-verify workflow with explicit checkpoints for each design concern. Not 5 because there is no error-recovery feedback loop and the material is a reference catalog rather than a validated multi-step sequence; not 3 because checkpoints are explicit, not merely implied.

4 / 5

Progressive Disclosure

Section headers and structure are good, but there are no bundle files at all: the full pattern catalog and three-language implementation examples are inlined in SKILL.md, where the rubric expects bulk detail to be split into one-level-deep references. Not 4 because nothing is split out; not 2 because the content is clearly organized with headers rather than being a structureless wall.

3 / 5

Total

14

/

20

Passed

Description

66%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.

The description is specific, domain-rich, and reasonably distinct, clearly communicating what the skill covers. Its main weakness is the absence of any 'Use when...' trigger guidance, which caps completeness and weakens discoverability. Adding an explicit activation clause would lift it substantially.

Suggestions

Add an explicit trigger clause, e.g. "Use when designing or reviewing REST API endpoints, adding pagination or error handling, or planning API versioning."

Include natural user synonyms such as "endpoints", "HTTP API", and "OpenAPI/Swagger" to improve trigger-term coverage.

Mention authentication and response-format conventions in the description to close the coverage gaps with the body content.

DimensionReasoningScore

Specificity

Enumerates seven concrete capability areas ("resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting") with comprehensive domain coverage, but they are noun-phrase domains rather than concrete actions and minor gaps exist (no mention of authentication or response formats). Not 5 because the anchors at that level demand fully concrete action coverage; not 3 because far more than 1-2 areas are named.

4 / 5

Completeness

Has a clear, specific 'what' but no 'Use when...' clause or equivalent explicit trigger guidance, which caps completeness at 3 per the judging guidelines. Not 4 because the 'when' is entirely absent rather than merely weak.

3 / 5

Trigger Term Quality

Contains natural phrases users would say such as "REST API", "status codes", "pagination", "rate limiting", and "production APIs". Not 5 because common variations and synonyms are missing (e.g., "endpoints", "HTTP API", "OpenAPI/Swagger"); not 3 because keyword coverage goes well beyond 'some relevant keywords'.

4 / 5

Distinctiveness Conflict Risk

"REST API design patterns ... for production APIs" carves out a clear niche with distinct triggers (REST, status codes, versioning). Not 5 because of some overlap risk with general backend/web-development skills; not 3 because the topic is more specific than 'somewhat specific'.

4 / 5

Total

15

/

20

Passed

Validation

87%

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

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

skill_md_line_count

SKILL.md is long (526 lines); consider splitting into references/ and linking

Warning

metadata_version

'metadata.version' is missing

Warning

Total

14

/

16

Passed

Repository
affaan-m/ECC
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.