api-patterns

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

Quality

70%

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

72%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content body is a concise, well-organized overview that uses progressive disclosure effectively via a content map and verified references. Its weakness is actionability and workflow clarity: most guidance points to referenced files rather than embedding executable examples, and the decision workflow lacks explicit validation checkpoints.

Suggestions

Add at least one concrete, copy-paste-ready example inline (e.g. a minimal REST resource + status-code snippet or a sample response envelope) so the skill is actionable without opening every reference.

Strengthen the decision workflow with an explicit validation/feedback checkpoint, such as 'validate the chosen design against the checklist and revise before finalizing', to close the verify→fix loop.

Dimension	Reasoning	Score
Conciseness	The body is lean and well-structured with tables and short checklists that assume Claude's competence; it avoids explaining basic concepts Claude already knows and every section earns its place.	3 / 3
Actionability	Provides concrete structure (content map, decision checklist, anti-patterns, script command) but most guidance is directional rather than executable — the actual design how-tos live in referenced files, and the body lacks copy-paste-ready examples beyond the single validator command.	2 / 3
Workflow Clarity	The decision checklist gives a sequenced set of pre-design steps, but there are no explicit validation checkpoints or feedback loops; for a decision-making skill this is acceptable but the sequence lacks verify/retry gates, so it does not reach the 3-anchor.	2 / 3
Progressive Disclosure	Clear overview with a well-signaled content map pointing one level deep to topic files, a related-skills table, and a verified script entry (scripts/api_validator.py exists); navigation is explicit and easy.	3 / 3
	Total	10 / 12 Passed

Description

67%

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 well-scoped to API design, naming concrete capabilities and a clear niche. Its main weakness is the absence of an explicit 'Use when...' trigger clause in the description itself and reliance on technical jargon over natural user language.

Suggestions

Add an explicit 'Use when...' trigger clause directly in the description (e.g. 'Use when designing or choosing between REST/GraphQL/tRPC APIs, or when planning response formats, versioning, pagination, or auth.')

Broaden trigger terms toward natural user phrasing by adding terms like 'API', 'endpoints', 'web service', or 'backend design' alongside the technical style names.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions: 'REST vs GraphQL vs tRPC selection, response formats, versioning, pagination' — names several specific capabilities rather than vague language.	3 / 3
Completeness	Clearly states what the skill does, but the description itself lacks an explicit 'Use when...' trigger clause — that guidance is only present in the separate when_to_use field, so completeness is capped at 2 per the rubric.	2 / 3
Trigger Term Quality	Includes recognizable technical terms (REST, GraphQL, tRPC, versioning, pagination) but these are more jargon than natural user phrasing and lack common variations users would say, e.g. 'API', 'endpoint', 'web service'.	2 / 3
Distinctiveness Conflict Risk	Niche is clear and distinct (API design/decision-making across REST/GraphQL/tRPC) and unlikely to trigger for unrelated skills; the specificity anchors it to a well-defined domain.	3 / 3
	Total	10 / 12 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: 04514f0

Reviewed: about 12 hours 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.