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. Use when designing or reviewing REST endpoints, resource names, status codes, pagination, or versioning.

67

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

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

SKILL.md
Quality
Evals
Security

Quality

Content

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

Highly actionable and well-structured reference content with excellent concrete examples across three languages, but it is a monolithic 500+ line SKILL.md that both re-teaches HTTP basics Claude already knows and inlines material (per-language implementation patterns) that belongs in one-level-deep reference files.

Suggestions

Move the per-language implementation examples (TypeScript/Next.js, Python/DRF, Go) into references/ files (e.g. references/examples.md) and keep only one representative example inline, reducing the main file to a lean overview with clearly signaled one-level-deep links.

Cut the sections that restate standard knowledge Claude already has — the HTTP method semantics table and the basic 2xx/4xx/5xx status-code reference — and retain only the project-specific conventions (error envelope shape, 409/422 usage rules, Location-header policy).

Turn the final checklist into an explicit validation loop for the endpoint workflow (e.g., 'run the checklist; if any item fails, fix and re-verify before shipping') to add a feedback checkpoint the current static checklist lacks.

DimensionReasoningScore

Conciseness

The body is prose-free and table/code-dense (no padded explanations), but a substantial share restates concepts Claude already knows — the HTTP method idempotency/safety table, the 200/201/204/400/401/403/404 status-code reference, and Bearer-token auth basics. This lands on 'mostly efficient but includes some unnecessary explanation or could be tightened'; it is not the level-2 case because there is no padded prose, and not level 4 because the re-taught basics are systematic rather than minor.

3 / 5

Actionability

Everything is concrete and executable: exact URL patterns with GOOD/BAD contrasts, SQL implementations for both pagination styles, runnable TypeScript/Python/Go handlers, exact rate-limit headers, and a pre-ship checklist. This matches 'fully executable; copy-paste ready code or commands; specific examples cover the common cases'.

5 / 5

Workflow Clarity

As a patterns/reference skill it still sequences decisions well: a numbered versioning strategy with a deprecation timeline, a 'When to Activate' section, and a final pre-ship checklist acting as a checkpoint. It stops short of anchor 5 because there are no explicit validate-then-fix feedback loops (e.g., 'if the checklist fails, fix and re-check'), and it sits above anchor 3 because checkpoints (the checklist, the deprecation steps) are explicit.

4 / 5

Progressive Disclosure

No bundle files exist (references/, scripts/, assets/ are absent) and the entire ~520-line reference lives inline in SKILL.md; content that clearly belongs in separate files — three language-specific implementation examples and full reference tables — is inlined with no external references. Section headers are well-organized, matching 'some structure but could be better organized; content that should be separate is inline' rather than level 2's 'minimal structure', since navigation via headers is genuinely easy.

3 / 5

Total

15

/

20

Passed

Description

92%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 description: concrete, third-person, buzzword-free, with an explicit 'Use when' trigger clause covering the main use cases. The only minor gap is that a few capability areas named in the what-clause (error handling, filtering, rate limiting) are absent from the trigger list.

DimensionReasoningScore

Specificity

Names multiple concrete capability areas — 'resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting' — giving comprehensive coverage of the REST design domain with no filler. This matches the anchor 'lists multiple specific concrete actions; comprehensive coverage'; the level below (4) would require minor coverage gaps, and none are evident.

5 / 5

Completeness

It explicitly answers both: what ('REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting') and when ('Use when designing or reviewing REST endpoints, resource names, status codes, pagination, or versioning'), with concrete trigger phrases. This matches the anchor-5 example's structure; anchor 4 would require the 'when' to be less explicit, which it is not.

5 / 5

Trigger Term Quality

The 'Use when' clause carries natural terms users would say — 'designing or reviewing REST endpoints, resource names, status codes, pagination, or versioning'. This is good coverage but a few natural phrasings (e.g., 'error handling', 'rate limiting', 'API design') are present in the what-clause yet omitted from the triggers, so it sits between the good (4) and comprehensive (5) anchors, closer to 4.

4 / 5

Distinctiveness Conflict Risk

It occupies a clear niche (REST API design conventions) with distinct triggers like 'REST endpoints', 'resource names', and 'versioning', minimizing risk of firing for unrelated skills. The only adjacent space ('reviewing endpoints') mildly overlaps generic code-review skills, but not enough to drop below the 'clear niche' anchor.

5 / 5

Total

19

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

skill_md_line_count

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

Warning

Total

15

/

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.