code-documentation-doc-generate

You are a documentation expert specializing in creating comprehensive, maintainable documentation from code. Generate API docs, architecture diagrams, user guides, and technical references using AI-powered analysis and industry best practices.

Quality

20%

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 ./plugins/antigravity-awesome-skills/skills/code-documentation-doc-generate/SKILL.md

Quality

Content

7%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 essentially a high-level abstract description of documentation generation with no concrete, actionable guidance. It reads more like a role description than a skill that Claude can execute. The content lacks executable code examples, specific tool recommendations, concrete workflows, and validation steps, making it largely unusable as practical instruction.

Suggestions

Add concrete, executable examples for at least one documentation type (e.g., generating API docs with a specific tool like pydoc, Sphinx, or TypeDoc, with actual commands and configuration snippets).

Replace vague instruction bullets with a clear, sequenced workflow including validation checkpoints (e.g., 'Run `sphinx-build -b html docs/ docs/_build/` and verify no warnings before committing').

Remove boilerplate sections (Context, Limitations, 'Use this skill when') that don't add actionable information, and use the saved space for concrete examples and templates.

Provide the referenced `resources/implementation-playbook.md` bundle file, or inline the most critical templates and examples directly in the skill body.

Dimension	Reasoning	Score
Conciseness	The content is verbose and padded with unnecessary context that Claude already knows. Sections like 'Use this skill when', 'Do not use this skill when', 'Context', and 'Limitations' are largely boilerplate that don't add actionable value. The instructions themselves are vague bullet points that could be significantly tightened.	1 / 3
Actionability	The skill provides no concrete code, commands, specific tool configurations, or executable examples. Instructions like 'Extract information from code, configs, and comments' and 'Generate docs with consistent terminology and structure' are abstract descriptions rather than actionable guidance. There are no copy-paste ready snippets, no specific tool invocations, and no example inputs/outputs.	1 / 3
Workflow Clarity	The instructions list vague steps without clear sequencing, validation checkpoints, or feedback loops. Steps like 'Add automation (linting, CI) and validate accuracy' conflate multiple complex tasks into a single bullet with no detail on how to validate or what constitutes success. There is no error recovery guidance.	1 / 3
Progressive Disclosure	The skill references `resources/implementation-playbook.md` for detailed examples and templates, which is a reasonable one-level-deep reference. However, no bundle files are provided, so the reference cannot be verified. The main content itself lacks enough substance to serve as a useful overview, making the reference feel like a crutch for missing content rather than genuine progressive disclosure.	2 / 3
	Total	5 / 12 Passed

Description

32%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 identifies a clear domain (documentation generation from code) and lists several output types, but relies on buzzwords like 'AI-powered analysis' and 'industry best practices' instead of concrete actions. It critically lacks any 'Use when...' clause, making it difficult for Claude to know when to select this skill. The use of second-person voice ('You are') violates the third-person requirement.

Suggestions

Add an explicit 'Use when...' clause with trigger terms like 'generate docs', 'document this code', 'API reference', 'README', 'write documentation'.

Replace vague phrases like 'AI-powered analysis and industry best practices' with specific actions such as 'parses function signatures, extracts docstrings, maps module dependencies'.

Rewrite in third person voice (e.g., 'Generates API docs, architecture diagrams...' instead of 'You are a documentation expert...').

Dimension	Reasoning	Score
Specificity	Names the domain (documentation from code) and lists some outputs (API docs, architecture diagrams, user guides, technical references), but uses vague qualifiers like 'AI-powered analysis' and 'industry best practices' which are buzzwords rather than concrete actions.	2 / 3
Completeness	Describes what it does (generate various documentation types) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, missing 'Use when' caps completeness at 2, and the 'what' is also somewhat vague, warranting a 1.	1 / 3
Trigger Term Quality	Includes some relevant keywords like 'API docs', 'architecture diagrams', 'user guides', 'technical references', and 'documentation', but misses common user variations like 'README', 'docstrings', 'JSDoc', 'swagger', or 'code comments'. The terms are reasonable but not comprehensive.	2 / 3
Distinctiveness Conflict Risk	The documentation focus provides some distinctiveness, but 'documentation from code' is broad enough to overlap with code commenting skills, README generators, or general writing skills. The mention of architecture diagrams could also conflict with diagramming skills.	2 / 3
	Total	7 / 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: popey/claude-code-skills
Path: plugins/antigravity-awesome-skills/skills/code-documentation-doc-generate/SKILL.md
Commit: a5a6601

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