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.

Install with Tessl CLI

npx tessl i github:sickn33/antigravity-awesome-skills --skill api-documenter

What are skills?

1.00x

Quality

22%

Does it follow best practices?

Impact

100%

1.00x

Average score across 3 eval scenarios

Optimize this skill with Tessl

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

SKILL.md

Review

Evals

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 several concrete outputs, but suffers from marketing-style language ('Master', 'modern developer experience practices') and critically lacks any 'Use when...' guidance. The absence of explicit trigger conditions makes it difficult for Claude to know when to select this skill from a large pool.

Suggestions

Add a 'Use when...' clause with explicit triggers like 'Use when the user asks about OpenAPI specs, Swagger files, API documentation, SDK generation, or developer portal creation'

Replace vague terms like 'Master' and 'AI-powered tools' with specific actions (e.g., 'Validates OpenAPI specs, generates client SDKs in multiple languages')

Include common user terms and file extensions: 'swagger', 'API spec', '.yaml', '.json', 'REST API docs'

Dimension	Reasoning	Score
Specificity	Names the domain (API documentation, OpenAPI 3.1) and lists some actions (create interactive docs, generate SDKs, build developer portals), but uses vague terms like 'Master' and 'AI-powered tools' without explaining what those tools do specifically.	2 / 3
Completeness	Describes what it does but completely lacks a 'Use when...' clause or any explicit trigger guidance. There is no indication of when Claude should select this skill over others.	1 / 3
Trigger Term Quality	Includes some relevant keywords like 'OpenAPI 3.1', 'API documentation', 'SDKs', 'developer portals', but missing common variations users might say like 'swagger', 'API spec', 'REST docs', 'API reference', or file extensions like '.yaml', '.json'.	2 / 3
Distinctiveness Conflict Risk	OpenAPI 3.1 and SDK generation provide some distinctiveness, but 'API documentation' and 'developer experience practices' are broad enough to potentially overlap with general documentation or coding skills.	2 / 3
	Total	7 / 12 Passed

Implementation

12%

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

This skill reads like a capability manifest or persona description rather than actionable documentation. It extensively lists what Claude should know and be able to do, but provides zero concrete examples, code snippets, or executable commands. The content is extremely verbose, explaining concepts Claude already understands while failing to provide the specific, actionable guidance that would make this skill useful.

Suggestions

Replace capability lists with concrete, executable examples - e.g., provide an actual OpenAPI 3.1 template with annotations, specific CLI commands for SDK generation tools like openapi-generator

Add working code examples for key tasks: a complete OpenAPI spec snippet, curl commands for testing, actual Swagger UI configuration code

Remove the 'Capabilities', 'Behavioral Traits', and 'Knowledge Base' sections entirely - these describe what Claude already knows and waste tokens

Create separate reference files (e.g., OPENAPI_TEMPLATES.md, SDK_GENERATION.md) and link to them from a concise overview, rather than listing everything inline

Dimension	Reasoning	Score
Conciseness	Extremely verbose with extensive lists of capabilities, knowledge bases, and behavioral traits that Claude already knows. The content reads like a job description rather than actionable instructions, with significant padding that doesn't add operational value.	1 / 3
Actionability	No concrete code examples, commands, or executable guidance anywhere. The entire skill describes capabilities and concepts abstractly without providing any actual implementation details, code snippets, or specific tool commands.	1 / 3
Workflow Clarity	The Instructions section provides a basic 4-step sequence and Response Approach lists 8 steps, but these are high-level and lack validation checkpoints, specific commands, or feedback loops for error recovery.	2 / 3
Progressive Disclosure	Monolithic wall of text with no references to external files or resources. All content is inline in one massive document with no clear navigation structure or links to detailed materials for specific topics.	1 / 3
	Total	5 / 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

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