api-documenter

Master API documentation with OpenAPI 3.1, AI-powered tools, and modern developer experience practices. Create interactive docs, generate SDKs, and build comprehensive developer portals.

Quality

16%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/api-documenter/SKILL.md

Quality

Discovery

32%

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 identifies a clear domain (API documentation with OpenAPI) and lists some concrete outputs (interactive docs, SDKs, developer portals), but suffers from vague buzzwords ('Master', 'AI-powered tools', 'modern developer experience practices') and completely lacks explicit trigger guidance. It would benefit significantly from a 'Use when...' clause and more natural user-facing keywords.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user asks about API documentation, OpenAPI/Swagger specs, generating SDKs, or building developer portals.'

Replace vague phrases like 'Master API documentation' and 'AI-powered tools' with concrete actions such as 'Write and validate OpenAPI 3.1 specifications, generate client SDKs, create API reference pages.'

Include common keyword variations users would naturally say: 'Swagger', 'REST API docs', 'API spec', 'API reference', '.yaml spec files', 'API endpoints documentation'.

Dimension	Reasoning	Score
Specificity	Names the domain (API documentation) and lists some actions like 'Create interactive docs, generate SDKs, and build comprehensive developer portals,' but also includes vague phrases like 'Master API documentation' and 'modern developer experience practices' which are more aspirational than concrete.	2 / 3
Completeness	Describes what it does (create docs, generate SDKs, build portals) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, missing 'Use when' caps completeness at 2, and the 'what' is also somewhat vague, so this scores a 1.	1 / 3
Trigger Term Quality	Includes some relevant keywords like 'OpenAPI 3.1', 'SDKs', 'developer portals', and 'API documentation', but misses common user variations like 'Swagger', 'REST API docs', 'API spec', 'API reference', or '.yaml/.json spec files'. 'AI-powered tools' is vague and unlikely to be a natural trigger.	2 / 3
Distinctiveness Conflict Risk	The mention of OpenAPI 3.1 and SDK generation provides some distinctiveness, but 'API documentation' and 'developer portals' are broad enough to overlap with general documentation skills or web development skills. 'AI-powered tools' adds confusion about scope.	2 / 3
	Total	7 / 12 Passed

Implementation

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

This skill reads as a capability catalog or persona description rather than actionable instructions. It lists dozens of topics Claude should know about but provides zero concrete examples, executable code, specific commands, or real workflows. The content is almost entirely descriptive rather than instructive, violating the core principle that skills should teach Claude how to perform specific tasks with concrete, executable guidance.

Suggestions

Replace the massive 'Capabilities' bullet lists with 2-3 concrete, executable examples (e.g., a minimal OpenAPI 3.1 spec template, a curl command for spec validation, a SDK generation command)

Add a concrete workflow with validation checkpoints, e.g., 'Write spec → validate with spectral lint → generate mock server → test endpoints → generate SDK'

Remove 'Behavioral Traits', 'Knowledge Base', and 'Example Interactions' sections entirely—they consume tokens without adding actionable value

Include at least one complete, copy-paste-ready OpenAPI 3.1 snippet showing the specific patterns and conventions you want Claude to follow

Dimension	Reasoning	Score
Conciseness	Extremely verbose and padded with information Claude already knows. The massive 'Capabilities' section is essentially a taxonomy of API documentation topics that provides no actionable guidance—it reads like a resume or marketing brochure. 'Behavioral Traits' and 'Knowledge Base' sections restate obvious qualities. The entire document could be reduced by 80%+ without losing useful information.	1 / 3
Actionability	Despite being about API documentation, there is zero executable code, no concrete OpenAPI spec examples, no specific commands, no tool invocations, and no copy-paste-ready snippets. Everything is described at an abstract level ('OpenAPI 3.1+ specification authoring with advanced features') without showing how to actually do anything.	1 / 3
Workflow Clarity	The 'Instructions' section lists 4 extremely vague steps ('Create or validate specifications with examples and auth flows') with no concrete details, no validation checkpoints, and no error recovery. The 'Response Approach' is similarly abstract. For a skill involving spec authoring and SDK generation, there are no actual workflows with verification steps.	1 / 3
Progressive Disclosure	The content is a monolithic wall of bullet-pointed lists with no external references, no linked files, and no layered structure. All content is inline at the same level of abstraction. There are no bundle files to reference, yet the massive amount of topic coverage would clearly benefit from being split into focused sub-documents.	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: sickn33/antigravity-awesome-skills
Commit: 8854d4e

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