api-documentation

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

Quality

58%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/antigravity-api-documentation/SKILL.md

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

Quality

Content

50%Weight 40%Scale 1-5

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

The workflow is well-sequenced and concise, but it offers little executable guidance beyond delegating to other skills and lacks per-phase validation checkpoints. With no bundle files, progressive disclosure is limited to an inlined single-file structure.

Suggestions

Add concrete, executable artifacts per phase (e.g., a starter OpenAPI YAML skeleton, a curl example template, a Swagger UI config snippet) instead of bare imperatives and skill-delegation prompts.

Insert per-phase validation checkpoints (e.g., validate the OpenAPI spec with `swagger-cli validate` before moving to the developer guide) and feedback loops, since this workflow involves batch generation and spec validation.

Move detailed per-phase reference material into one-level-deep bundle files under references/ (e.g., openapi-template.yaml, developer-guide-template.md) and link them from each phase to improve progressive disclosure.

Dimension	Reasoning	Score
Conciseness	The body is lean with compact bullet lists and no concept over-explanation, but the six near-identical 'Copy-Paste Prompts' repeating `Use @api-documenter to...` are minor redundancy, placing it just below a 5.	4 / 5
Actionability	Actions are bare imperatives ('Inventory endpoints', 'Create OpenAPI schema', 'Define paths') with no executable code, commands, or templates, and the copy-paste prompts merely delegate to other skills, matching the 'minimal concrete guidance; high-level hints' anchor.	2 / 5
Workflow Clarity	Phases are clearly sequenced (1-7) with an end Quality Gates checklist, but there are no per-phase validation checkpoints or feedback loops for batch/spec-validation operations, so the destructive/batch validation cap holds it at 3.	3 / 5
Progressive Disclosure	No bundle files exist and all seven phases' detail is inlined in SKILL.md with no one-level-deep file references to navigate to; section headers provide structure but content that could be separate remains inline, fitting the 3 anchor.	3 / 5
	Total	12 / 20 Passed

Description

66%Weight 40%Scale 1-5

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 states a clear 'what' with several concrete actions and decent trigger keywords, but omits any explicit 'when to use' trigger clause, which caps completeness. It is reasonably distinct but could clarify triggers and add synonyms.

Suggestions

Add an explicit 'Use when...' clause naming concrete trigger phrases (e.g., 'Use when generating OpenAPI/Swagger specs, writing API developer guides, or building API documentation portals').

Include synonyms and file extensions users actually say, such as 'Swagger', 'REST docs', 'API reference', and '.yaml/.json specs' to broaden trigger coverage.

Sharpen 'maintaining comprehensive API documentation' into more specific actions (e.g., 'automating spec regeneration and validating spec compliance') to push specificity toward 5.

Dimension	Reasoning	Score
Specificity	Lists three concrete actions ('generating OpenAPI specs, creating developer guides, and maintaining comprehensive API documentation') with only minor coverage gaps, matching the 'lists several specific actions' anchor rather than the 1-2 actions of a 3.	4 / 5
Completeness	Has a clear 'what' but no 'Use when...' or equivalent explicit trigger guidance, so per the judging guideline the missing trigger clause caps completeness at 3.	3 / 5
Trigger Term Quality	Includes natural terms like 'API documentation', 'OpenAPI specs', and 'developer guides', but omits common synonyms/extensions users say (Swagger, REST docs, API reference, .yaml), fitting the 'good keyword coverage; a few natural terms missing' anchor.	4 / 5
Distinctiveness Conflict Risk	The API-documentation/OpenAPI-spec niche is mostly distinct with only minor overlap risk against general documentation skills, though the body's many overlapping skill references (api-documenter, api-documentation-generator, documentation) keep it from a 5.	4 / 5
	Total	15 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

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

	Total	15 / 16 Passed

Repository: boisenoise/skills-collections
Path: skills/antigravity-api-documentation/SKILL.md
Commit: 652629d

Reviewed: ~12 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.