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.

1.00x

Quality

50%

Does it follow best practices?

Impact

100%

1.00x

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-documenter/SKILL.md

The canonical home for this skill is api-documenter in rmyndharis/antigravity-skills

Quality

Content

35%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 body reads as a persona/capability profile rather than executable guidance: it enumerates what the skill knows and does at a high level without concrete code, commands, or validation checkpoints. Structure is present but most detail belongs in referenced files.

Suggestions

Replace the descriptive Capabilities/Knowledge Base/Behavioral Traits lists with concrete, executable guidance (e.g. example OpenAPI snippets, a Spectral validation command, an SDK generation command).

Add explicit validation checkpoints to the workflow (e.g. validate the spec with a linter before generating SDKs, and only proceed on success).

Move the lengthy capability and knowledge enumerations into reference files and keep SKILL.md as a concise overview pointing to them.

Dimension	Reasoning	Score
Conciseness	The body is noticeably verbose and padded with persona language and capability/knowledge enumerations Claude already knows ("You are an expert...", "Knowledge Base", "Behavioral Traits") that add little actionable signal; not a 1 because it stops short of explaining elementary concepts.	2 / 5
Actionability	Guidance is almost entirely descriptive lists ("OpenAPI 3.1+ specification authoring with advanced features", "AI-assisted content generation with tools like Mintlify") with no executable code or commands; the numbered Instructions/Response Approach give only high-level hints.	2 / 5
Workflow Clarity	A rough sequence exists (4-step Instructions, 8-step Response Approach) but validation checkpoints are only implicit ("ensure accuracy with tests") rather than explicit validate-then-proceed gates.	3 / 5
Progressive Disclosure	Sections are well-organized with headers, but the skill is a monolithic ~175-line file with large capability and knowledge-base blocks inlined that would be better split into referenced files; no bundle files exist.	3 / 5
	Total	10 / 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 communicates concrete actions and a clear niche but omits any explicit "Use when..." trigger clause, which caps its completeness. Keyword coverage is good though not exhaustive of common synonyms.

Suggestions

Add an explicit trigger clause, e.g. "Use when creating or updating OpenAPI/AsyncAPI specs, building developer portals or SDK docs, or generating SDKs from API specs."

Trim the buzzword-heavy opening ("Master... AI-powered tools, and modern developer experience practices") in favor of more concrete verbs.

Include common synonyms/file extensions users say (Swagger, API spec, .yaml/.json) to broaden natural trigger matching.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ("Create interactive docs, generate SDKs, and build comprehensive developer portals") though the opening clause ("Master API documentation with OpenAPI 3.1, AI-powered tools, and modern developer experience practices") leans on buzzwords and leaves minor coverage gaps.	4 / 5
Completeness	The "what" is clear but there is no "Use when..." clause or equivalent explicit trigger guidance, so per the rubric completeness is capped at 3.	3 / 5
Trigger Term Quality	Good coverage of natural keywords ("API documentation", "OpenAPI 3.1", "interactive docs", "SDKs", "developer portals") that users would plausibly say, with a few common synonyms missing (e.g. "Swagger", "spec", ".yaml").	4 / 5
Distinctiveness Conflict Risk	It carves a clear API-documentation niche with mostly distinct triggers, with only minor overlap risk against generic documentation or code-generation skills; not a 5 because triggers are not made explicit.	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: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: plugins/AI-Agents-Safe-Coding-Skills/skills/api-documenter/SKILL.md
Commit: 900c504

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