CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

api-design

Patrones de diseño REST API incluyendo nomenclatura de recursos, códigos de estado, paginación, filtrado, respuestas de error, versionado y rate limiting para APIs de producción.

56

Quality

70%

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 ./docs/es/skills/api-design/SKILL.md
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.

A well-structured, highly actionable reference with concrete conventions, contrasting good/bad examples, and a useful pre-publish checklist. It is held back by sections that restate standard REST knowledge Claude already has, minor inexecutable gaps in two of three language examples, and the absence of any progressive disclosure — everything is inlined in one long SKILL.md with no reference files.

Suggestions

Trim sections that restate standard knowledge (the HTTP method semantics table and the plain status-code meanings) down to only project-specific conventions like the BIEN/MAL contrasts and envelope format choices.

Move the per-language implementation examples (TypeScript/Python/Go) into references/ files (e.g., references/implementations.md) and keep the decision tables and format examples inline in SKILL.md.

Fix the small executability gaps: define or import the writeError/writeJSON helpers in the Go example and import IsAuthenticated in the DRF example.

DimensionReasoningScore

Conciseness

Much of the body adds real value (BIEN/MAL contrasts, pagination trade-off tables, versioning deprecation timeline), but several sections restate knowledge Claude already has — the HTTP method idempotency/safety table, the full status-code meanings list (200 OK, 404 Not Found), and basic OFFSET/LIMIT SQL — fitting anchor 3's "mostly efficient but includes some unnecessary explanation".

3 / 5

Actionability

Guidance is overwhelmingly concrete — copy-paste URL patterns, JSON envelope examples, and full TypeScript/Python/Go implementations — but there are minor gaps: the Go example calls undefined writeError/writeJSON helpers and the DRF example uses IsAuthenticated without importing it, matching anchor 4 rather than fully executable anchor 5.

4 / 5

Workflow Clarity

The reference is well organized with a "Cuándo Activar" section, a numbered versioning strategy, and a final pre-publish checklist ("Antes de publicar un nuevo endpoint") serving as an explicit validation checkpoint — but there is no sequenced workflow for designing a new endpoint, so it fits anchor 4 with minor validation gaps rather than anchor 5's explicit feedback loops.

4 / 5

Progressive Disclosure

Section headers are clear, but all ~520 lines live inline in SKILL.md with no reference files at all; content that clearly belongs in separate files (the ~100 lines of per-language implementation examples, the detailed filtering/sorting reference) is inlined, matching anchor 3's "content that should be separate is inline".

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.

A specific, well-scoped description that names the domain and enumerates seven concrete capability areas in third person, with good natural trigger keywords. Its main weakness is the total absence of an explicit "Use when..." clause, which caps completeness at 3 and leaves activation guidance implicit.

Suggestions

Append an explicit trigger clause, e.g. "Use when designing or reviewing REST API endpoints, adding pagination, filtering, or error handling, or planning API versioning for production APIs."

Add commonly used natural trigger terms such as "endpoints" or "diseño de endpoints" to broaden keyword coverage toward anchor 5.

Mention authentication/authorization patterns if they are in scope (the body covers them), or keep the description's enumerated areas aligned with the body's actual coverage.

DimensionReasoningScore

Specificity

The description lists several specific concrete areas — "nomenclatura de recursos, códigos de estado, paginación, filtrado, respuestas de error, versionado y rate limiting" — giving comprehensive topical coverage, but they are scope nouns rather than actions and areas like authentication are omitted, matching anchor 4 rather than 5.

4 / 5

Completeness

The "what" is clear (REST API design patterns across seven named areas), but there is no "Use when..." clause or equivalent trigger guidance anywhere in the description, which caps completeness at 3 per the judging guidelines.

3 / 5

Trigger Term Quality

Good keyword coverage with natural terms users would say — "REST API", "paginación", "versionado", "filtrado", "rate limiting" (kept in English, as users would) — but common variations like "endpoints"/"diseño de endpoints" are missing, fitting anchor 4 rather than the comprehensive synonym coverage of anchor 5.

4 / 5

Distinctiveness Conflict Risk

"Patrones de diseño REST API" with triggers like paginación, versionado, and rate limiting carves a mostly distinct niche; only minor overlap risk with closely related skills such as general backend/web-service or GraphQL design skills, matching anchor 4.

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 (524 lines); consider splitting into references/ and linking

Warning

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

14

/

16

Passed

Repository

affaan-m/ECC

Path

docs/es/skills/api-design/SKILL.md

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.