api-patterns

API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.

1.16x

Quality

60%

Does it follow best practices?

Impact

99%

1.16x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/api-patterns/SKILL.md

Quality

Content

53%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 well organized and token-efficient with a sensible decision checklist and a genuinely useful worked example, but it functions as an index to reference files that are missing from the bundle. The skill's core value (the actual decision tree and design guidance) is therefore unreachable in practice.

Suggestions

Create the ten referenced files in the bundle (api-style.md, rest.md, response.md, graphql.md, trpc.md, versioning.md, auth.md, rate-limiting.md, documentation.md, security-testing.md) or inline the essential guidance each was meant to hold, since every content-map link currently resolves to nothing.

Add a concrete example payload — e.g. an actual cursor format and a sample success/error response envelope — so the worked example demonstrates the specified output rather than only describing it.

Break the "Inputs and procedure" paragraph into a numbered step sequence with an explicit validation checkpoint (e.g. "verify the rejection cases and compatibility constraints before finalizing the contract").

Dimension	Reasoning	Score
Conciseness	The body is efficient — tables, checklists, and terse sections with no explanation of concepts Claude already knows — but the motivational quotes ("Learn to THINK, not copy fixed patterns") and emoji headers are minor padding that could be trimmed.	4 / 5
Actionability	There is concrete guidance (the worked example specifies cursor over "(created_at, id)" ordering and test cases like "two equal timestamps"), but the substantive design content — the decision tree, status codes, and response formats — is deferred to reference files that do not exist in the bundle, leaving key details missing.	3 / 5
Workflow Clarity	A sequence exists ("Record consumers and deployed versions... Read the relevant files in the map, compare the realistic choices, then specify request/response examples and rejection cases") with a pre-flight checklist, but it is compressed into one dense paragraph and its central step points to files that are absent, leaving checkpoints implicit.	3 / 5
Progressive Disclosure	The content map with a "When to Read" column is well designed, but scored against the actual bundle all ten referenced paths (api-style.md, rest.md, response.md, etc.) are dangling — only scripts/api_validator.py exists — so the navigation structure does not resolve to any content.	2 / 5
	Total	12 / 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 concise, specific description that clearly conveys the skill's scope with strong natural keywords. Its main weakness is the absence of any explicit "Use when..." trigger clause, leaving the activation conditions implicit.

Suggestions

Append an explicit trigger clause, e.g. "Use when designing a new API, choosing between REST/GraphQL/tRPC, or defining response formats, versioning, or pagination behavior."

Add common synonym terms users naturally say, such as "endpoints", "API contract", or "OpenAPI", to broaden trigger coverage.

State the guidance in third-person action form (e.g. "Guides selection of...") to match the voice convention of strong examples.

Dimension	Reasoning	Score
Specificity	Lists several concrete capability areas — "REST vs GraphQL vs tRPC selection, response formats, versioning, pagination" — going beyond naming the domain alone, though these are topic areas rather than the fully comprehensive action coverage of a 5.	4 / 5
Completeness	The "what" is clear and concrete, but there is no "Use when..." clause or equivalent explicit trigger guidance, which caps completeness at 3 per the judging guidelines.	3 / 5
Trigger Term Quality	Natural keywords users would say are present ("REST vs GraphQL vs tRPC", "pagination", "versioning"), but common variations like "endpoints", "API contract", or "OpenAPI" are missing, so coverage is good rather than comprehensive.	4 / 5
Distinctiveness Conflict Risk	The API-design niche with named styles (REST/GraphQL/tRPC) is mostly distinct with clear triggers; only minor overlap risk with closely related skills like a general backend-architecture skill.	4 / 5
	Total	15 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

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

	Total	15 / 16 Passed

Repository: sickn33/agentic-awesome-skills
Path: skills/api-patterns/SKILL.md
Commit: 7b534bc

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.