CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

common-api-design

Apply REST API conventions — HTTP semantics, status codes, versioning, pagination, and OpenAPI standards for any framework. Use when designing endpoints, choosing HTTP methods, implementing pagination, or writing OpenAPI specs.

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

SKILL.md
Quality
Evals
Security

Quality

Content

75%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-organized, decision-dense standards skill that keeps examples and deep consumer rules in real one-level-deep reference files. Its main deductions are compact restatements of basic HTTP knowledge, the absence of any sequenced design workflow, and a broken cross-skill reference link.

Suggestions

Trim the textbook HTTP glossary — verb semantics and basic code meanings (200 success, 404 not found) are knowledge Claude already has; keep only the project-specific decisions like 422-for-business-rules and Retry-After on 429.

Fix or remove the broken cross-skill link to ../../quality-engineering/quality-engineering-api-testing/SKILL.md, which points at a nonexistent path and breaks navigation promised by the References section.

Add a brief sequenced checklist for the endpoint-design flow (design URLs → pick verbs/status codes → version → paginate → generate/review OpenAPI in PR) so the sections read as an ordered workflow rather than isolated topic rules.

DimensionReasoningScore

Conciseness

The body is mostly tight, decision-oriented bullets ("Default limit: 20, max 100", "URL path versioning default", RFC 9745/8594 header formats) that record team conventions Claude cannot infer, but sections like "HTTP Verb Semantics" and parts of "Status Code Correctness" (200 success, 404 not found, 401 unauthenticated) restate textbook HTTP knowledge Claude already has and could be trimmed — matching anchor 4's 'minor instances of over-explanation' rather than anchor 3, since the restatement is compact and the majority of content is non-obvious convention.

4 / 5

Actionability

Guidance is concrete and executable for an instruction-only skill: exact pagination envelope shape ({ data: [], pagination: { nextCursor, hasNextPage } }), specific header values (Deprecation: @<unix-seconds>, X-Frame-Options: DENY), concrete URL patterns with correct/incorrect examples, and the @Public() opt-out mechanism. It stops short of anchor 5 because full worked examples live in references/REFERENCE.md rather than the body, leaving minor gaps for the common cases inline.

4 / 5

Workflow Clarity

As a standards/reference skill there is no multi-step process to sequence, and each section unambiguously states the rule to apply; the "Review spec in PR — breaking changes need version bump" line and the anti-patterns section act as lightweight checkpoints. It does not reach 5 because the implicit design flow (design → version → paginate → document → review) is never sequenced, and it exceeds the under-50-line simple-skill exception; no destructive/batch cap applies.

4 / 5

Progressive Disclosure

The bundle structure is good: overview conventions inline in a ~65-line body, with both referenced files (references/REFERENCE.md for examples, references/consumer-contract.md for detailed consumer rules) present, one level deep, and clearly signaled with descriptive link text. It misses anchor 5 because the third reference — the cross-skill link to ../../quality-engineering/quality-engineering-api-testing/SKILL.md — points at a nonexistent path, a navigation defect.

4 / 5

Total

16

/

20

Passed

Description

83%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 that explicitly answers both what the skill does and when to use it, with an enumerated trigger clause and concrete domain coverage. Its only weaknesses are a generic main action verb ("Apply") and a few missing natural synonyms (RESTful, swagger, API design) in the trigger terms.

DimensionReasoningScore

Specificity

The description names the domain and enumerates five concrete coverage areas ("HTTP semantics, status codes, versioning, pagination, and OpenAPI standards") plus framework-agnostic scope, but the core action verb is a generic "Apply" — the concrete actions (designing endpoints, writing specs) appear only in the 'when' clause, leaving minor gaps versus anchor 5's comprehensive list of specific actions.

4 / 5

Completeness

Both parts are explicit: the 'what' is concrete ("Apply REST API conventions — HTTP semantics, status codes, versioning, pagination, and OpenAPI standards for any framework") and the 'when' is an explicit "Use when..." clause with concrete trigger phrases, matching anchor 5 exactly. Anchor 4 is ruled out because the 'when' clause is specific and enumerated rather than needing more detail.

5 / 5

Trigger Term Quality

Natural phrases users would say are well covered: "designing endpoints", "choosing HTTP methods", "implementing pagination", "writing OpenAPI specs", plus "REST API", "status codes", and "versioning" in the what-clause. A few common synonyms (e.g., "RESTful", "swagger", "API design") are missing, so it sits at anchor 4 rather than 5's comprehensive synonym coverage.

4 / 5

Distinctiveness Conflict Risk

The skill has a clear niche (REST API design conventions) with design-oriented triggers distinct from related skills, but "for any framework" and terms like "pagination"/"OpenAPI" create minor overlap risk with general backend-development, API-testing, or documentation-adjacent skills. Not anchor 5 because the conflict risk is minimal-but-present, not negligible.

4 / 5

Total

17

/

20

Passed

Validation

81%

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

Validation — 13 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

metadata_field

'metadata' should map string keys to string values

Warning

relative_links

Relative link issues: 1 suspicious

Warning

Total

13

/

16

Passed

Repository

HoangNguyen0403/agent-skills-standard

Path

.agents/skills/common/common-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.