api-patterns

API design principles and decision-making.

Quality

21%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Fix and improve this skill with Tessl

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

Quality

Content

42%

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

This skill is well-organized as a navigation hub with a clean content map, decision checklist, and anti-patterns section. However, it lacks any concrete, actionable content—no code examples, no executable commands, no specific API design patterns. With none of the 10 referenced files provided in the bundle, the skill is essentially an empty index that cannot deliver on its promise to teach API design principles.

Suggestions

Include at least one concrete, executable example in the SKILL.md itself (e.g., a sample REST endpoint design with request/response, or a decision tree with specific code outcomes).

Provide the referenced bundle files (rest.md, auth.md, response.md, etc.) so the progressive disclosure structure actually functions—without them, the content map is unusable.

Add a brief workflow with validation steps, e.g., 'Design endpoint → validate against OpenAPI spec → test with api_validator.py → review error responses' with concrete commands.

Replace or supplement the anti-patterns list with before/after code examples showing the wrong pattern and the corrected version.

Dimension	Reasoning	Score
Conciseness	The content is lean and well-structured. It avoids explaining what APIs are or how REST works—concepts Claude already knows. Every section serves a clear purpose: content map for navigation, checklist for decision-making, anti-patterns for guardrails.	3 / 3
Actionability	The SKILL.md contains no concrete code, commands, or executable examples. It's entirely composed of checklists, tables, and high-level guidance. The actual actionable content is deferred to referenced files (rest.md, auth.md, etc.), but none of those bundle files are provided, making the skill itself vague and non-executable.	1 / 3
Workflow Clarity	The decision checklist provides a reasonable sequence of considerations before designing an API, but there are no validation checkpoints, feedback loops, or explicit step-by-step workflows. For a skill about API design decision-making, the process of evaluating trade-offs and validating choices is not clearly sequenced.	2 / 3
Progressive Disclosure	The content map references 10 separate files (api-style.md, rest.md, response.md, etc.) and a script, but no bundle files are provided. This means the SKILL.md is essentially a table of contents pointing to nonexistent content, making it a hollow shell rather than a well-structured progressive disclosure system.	1 / 3
	Total	7 / 12 Passed

Description

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This description is far too vague and abstract to be useful for skill selection. It lacks concrete actions, natural trigger terms, any 'Use when...' guidance, and is generic enough to conflict with numerous other skills. It reads more like a topic heading than a functional skill description.

Suggestions

List specific concrete actions the skill covers, e.g., 'Designs RESTful API endpoints, defines resource naming conventions, selects authentication strategies, structures request/response schemas.'

Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks about API endpoint design, REST conventions, API versioning, request/response formats, or API architecture decisions.'

Narrow the scope to distinguish from related skills — specify whether this covers REST, GraphQL, gRPC, or all; whether it's about design review, greenfield design, or refactoring existing APIs.

Dimension	Reasoning	Score
Specificity	The description is extremely vague — 'API design principles and decision-making' names a broad domain but lists no concrete actions (e.g., designing endpoints, choosing REST vs GraphQL, writing OpenAPI specs).	1 / 3
Completeness	The description only vaguely hints at 'what' (API design) and completely omits any 'when' clause or explicit trigger guidance for when Claude should select this skill.	1 / 3
Trigger Term Quality	'API design principles' and 'decision-making' are abstract and generic terms. Users are more likely to say things like 'REST API', 'endpoint design', 'API versioning', or 'OpenAPI spec', none of which appear here.	1 / 3
Distinctiveness Conflict Risk	'API design principles and decision-making' is so broad it could overlap with backend development skills, architecture skills, REST skills, GraphQL skills, or general software design skills.	1 / 3
	Total	4 / 12 Passed

Validation

90%

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 — 10 / 11 Passed

Validation for skill structure

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

	Total	10 / 11 Passed

Repository: Dokhacgiakhoa/antigravity-ide
Commit: c4a059b

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