api-documentation

API documentation workflow for generating OpenAPI specs, creating developer guides, and maintaining comprehensive API documentation.

Quality

30%

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 ./plugins/antigravity-awesome-skills-claude/skills/api-documentation/SKILL.md

Quality

Content

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

This skill is a hollow skeleton that lists phases and action items without providing any concrete, actionable guidance. It reads like a project management outline rather than a skill that teaches Claude how to perform API documentation tasks. Every phase follows the same template of vague bullet points and trivial prompt suggestions, with zero executable code, specific examples, or real technical content.

Suggestions

Add concrete, executable examples: include an actual OpenAPI spec snippet, real curl commands, and SDK code examples in multiple languages rather than just listing 'Add curl examples' as an action item.

Replace vague action items with specific, step-by-step instructions that include actual commands, file paths, and expected outputs (e.g., show how to validate an OpenAPI spec with a specific tool and command).

Add validation checkpoints with concrete criteria between phases - for example, 'Validate OpenAPI spec: `npx @redocly/cli lint openapi.yaml` - fix all errors before proceeding to Phase 3.'

Either provide the referenced skill files (api-documenter, openapi-spec-generation, etc.) as bundle files, or remove the references and inline the essential content directly in this skill.

Dimension	Reasoning	Score
Conciseness	Extremely verbose and repetitive. Each phase follows an identical template with vague action lists that add no real information. The 'Copy-Paste Prompts' sections are trivial one-liners that don't provide actionable value. The entire skill could be condensed to a fraction of its size without losing any meaningful content.	1 / 3
Actionability	No concrete code, commands, or executable examples anywhere. Every action item is a vague directive like 'Create OpenAPI schema' or 'Configure security' without any specifics on how to do it. The 'Copy-Paste Prompts' are just generic invocations of other skills with no actual content. There's no OpenAPI spec example, no curl command, no code snippet.	1 / 3
Workflow Clarity	While phases are listed sequentially, the steps within each phase are superficial bullet points with no detail on execution, no validation checkpoints between phases, and no error recovery guidance. The 'Quality Gates' checklist at the end is disconnected from the workflow steps and provides no criteria for what 'complete' or 'working' means.	1 / 3
Progressive Disclosure	References multiple skills (api-documenter, openapi-spec-generation, etc.) but none of these are provided as bundle files, making the references unverifiable and potentially non-existent. The content is a monolithic wall of repetitive phase templates with no actual content split into supporting files. No bundle files are provided to support the many references.	1 / 3
	Total	4 / 12 Passed

Description

60%

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 does a good job listing specific capabilities around API documentation, but it lacks an explicit 'Use when...' clause which limits its effectiveness for skill selection. Adding trigger terms covering common synonyms (Swagger, REST docs) and explicit usage triggers would significantly improve it.

Suggestions

Add a 'Use when...' clause with explicit triggers, e.g., 'Use when the user asks about API docs, OpenAPI specs, Swagger files, REST API documentation, or endpoint references.'

Include common synonym trigger terms like 'Swagger', 'REST API', 'API reference', 'endpoint docs', '.yaml', '.json' to improve matching against natural user language.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions: 'generating OpenAPI specs', 'creating developer guides', and 'maintaining comprehensive API documentation'. These are distinct, actionable capabilities.	3 / 3
Completeness	Clearly answers 'what does this do' with specific actions, but lacks an explicit 'Use when...' clause or equivalent trigger guidance. The 'when' is only implied by the domain context.	2 / 3
Trigger Term Quality	Includes some relevant keywords like 'OpenAPI specs', 'API documentation', and 'developer guides', but misses common variations users might say such as 'Swagger', 'REST API docs', 'endpoint documentation', 'API reference', or file extensions like '.yaml'/'.json'.	2 / 3
Distinctiveness Conflict Risk	The focus on API documentation and OpenAPI specs provides some distinctiveness, but 'creating developer guides' and 'maintaining comprehensive API documentation' could overlap with general documentation or technical writing skills.	2 / 3
	Total	9 / 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: be20b37

Reviewed: 1 day 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.