api-documentation

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

1.11x

Quality

36%

Does it follow best practices?

Impact

95%

1.11x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./plugins/AI-Agents-Safe-Coding-Skills/skills/api-documentation/SKILL.md

The canonical home for this skill is api-documentation in sickn33/antigravity-awesome-skills

Quality

Content

12%Scale 1-3

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 high-level workflow outline that lacks any concrete, actionable content. It reads as a table of contents or project plan rather than a skill that teaches Claude how to perform specific tasks. Every phase follows an identical template of vague bullet points and trivial prompts, with no executable code, specific commands, real examples, or meaningful guidance.

Suggestions

Replace vague action items with concrete, executable examples — e.g., provide an actual OpenAPI spec snippet for Phase 2 instead of just 'Create OpenAPI schema'

Add real code examples (curl commands, SDK snippets, actual OpenAPI YAML) to make the skill actionable and copy-paste ready

Move detailed phase content into separate referenced files (e.g., OPENAPI_GUIDE.md, DEVELOPER_GUIDE.md) and keep SKILL.md as a concise overview with clear links

Add validation steps between phases — e.g., 'Validate OpenAPI spec with `swagger-cli validate openapi.yaml`' — to provide feedback loops for error recovery

Dimension	Reasoning	Score
Conciseness	Extremely verbose and repetitive structure. Each phase follows an identical template with vague bullet points that add no real information. The 'Copy-Paste Prompts' sections are trivial one-liners that don't provide meaningful guidance. The entire document could be condensed to a fraction of its size.	1 / 3
Actionability	No concrete code, commands, or executable examples anywhere. Every action item is vague ('Create OpenAPI schema', 'Configure security', 'Deploy docs') with no specifics on how to accomplish them. The 'Copy-Paste Prompts' just say 'Use @skill-name to do X' which is not actionable guidance.	1 / 3
Workflow Clarity	The phases are clearly sequenced and there is a quality gates checklist at the end, which provides some validation structure. However, there are no validation checkpoints between phases, no error recovery steps, and no feedback loops for when things go wrong.	2 / 3
Progressive Disclosure	The document is a monolithic wall of repetitive sections with no references to external files for detailed content. All seven phases are listed inline with identical shallow structure, and the referenced skills (e.g., @api-documenter, @openapi-spec-generation) are mentioned but never linked or explained.	1 / 3
	Total	5 / 12 Passed

Description

60%Scale 1-3

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 natural trigger terms and common synonyms (e.g., Swagger, REST docs) would improve discoverability and reduce potential overlap with general documentation skills.

Suggestions

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

Include common synonyms and variations users might say: 'Swagger', 'REST API docs', 'API reference', 'endpoint docs', '.yaml spec', 'API schema'.

Clarify the boundary with general documentation skills by specifying this is specifically for API/developer-facing documentation rather than general technical writing.

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: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: plugins/AI-Agents-Safe-Coding-Skills/skills/api-documentation/SKILL.md
Commit: 0159794

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