api-patterns

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

Quality

61%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

57%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-structured and concise with concrete checklists and anti-patterns, but its value is undercut because the detailed reference files it points to are missing from the bundle and the validator script is not integrated as an explicit workflow checkpoint.

Suggestions

Add the 10 referenced .md files to the bundle (api-style.md, rest.md, response.md, etc.) or remove their rows from the Content Map so signaled references actually resolve.

Wire the validator into the workflow as an explicit checkpoint, e.g. a checklist item 'Run `python scripts/api_validator.py <project_path>` and fix reported issues before finalizing.'

Drop or tighten the redundant epigraph / 'Selective Reading Rule' framing to lift conciseness from 4 to 5.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes Claude's competence — it never explains what REST/GraphQL/tRPC are — but the epigraph and 'Selective Reading Rule' slightly restate the description and the content map's purpose, leaving minor trimmable framing.	4 / 5
Actionability	Concrete guidance is present (a decision checklist, specific DO/DON'T anti-patterns like 'Use verbs in REST endpoints (/getUsers)', and an executable script command), but the core decision tree is delegated to api-style.md and the other reference files, which are not present in the bundle, leaving key details missing.	3 / 5
Workflow Clarity	The 'Decision Checklist' gives a clear pre-design sequence (consumers → style → response format → versioning → auth → rate limiting → documentation), but the available api_validator.py is not wired in as an explicit validation checkpoint, so verification steps are implicit.	3 / 5
Progressive Disclosure	The Content Map is an excellent one-level-deep, well-signaled overview (file, description, 'When to Read'), but 10 of the 11 referenced paths (api-style.md, rest.md, response.md, graphql.md, trpc.md, versioning.md, auth.md, rate-limiting.md, documentation.md, security-testing.md) do not exist in the bundle, so navigation to the detail layer is broken.	3 / 5
	Total	13 / 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 and uses natural trigger terms for the API-design domain, but it lacks an explicit 'Use when' clause, which caps completeness. Adding a trigger-guidance sentence would raise it to a strong 4-5 range.

Suggestions

Append an explicit 'Use when...' trigger clause to the description (e.g., 'Use when designing REST/GraphQL/tRPC APIs or planning versioning, pagination, and response formats.') to satisfy the completeness anchor.

Add a brief 'NOT for...' boundary phrase to the description to reduce overlap with general backend or frontend skills.

Optionally fold in auth and rate-limiting alongside the listed decisions to close the specificity coverage gap.

Dimension	Reasoning	Score
Specificity	Lists several concrete action areas — 'REST vs GraphQL vs tRPC selection, response formats, versioning, pagination' — naming the domain and four specific decisions, though it omits auth, rate-limiting, and documentation that appear in the body, leaving minor gaps.	4 / 5
Completeness	Gives a clear 'what' (API design principles and decision-making) but the description field has no 'Use when...' or equivalent explicit trigger clause, capping completeness at 3 per the rubric guideline.	3 / 5
Trigger Term Quality	Includes the natural paradigm terms users actually say ('REST', 'GraphQL', 'tRPC', 'versioning', 'pagination') with good coverage, though it misses common synonyms like 'endpoints' or 'web services'.	4 / 5
Distinctiveness Conflict Risk	The named paradigms (REST/GraphQL/tRPC) carve a clear API-design niche that is mostly distinct, with only minor overlap risk against closely related backend skills; no explicit 'not for X' boundary is present in the description itself.	4 / 5
	Total	15 / 20 Passed

Validation

87%

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

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	14 / 16 Passed

Repository: vudovn/ag-kit
Path: .agents/skills/api-patterns/SKILL.md
Commit: 549ba3d

Reviewed: 2 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.