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

37%

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/AI-Agents-Safe-Coding-Skills/skills/code-documentation-doc-generate/SKILL.md

Quality

Content

42%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 provides a reasonable high-level structure for documentation generation but lacks the concrete, actionable guidance needed for effective execution. The instructions are too abstract—describing tasks rather than providing executable commands, code snippets, or specific examples. The progressive disclosure is well-handled with clear references to external resources.

Suggestions

Add concrete code examples showing how to extract documentation from code (e.g., using docstring parsers, AST analysis, or specific tools like Sphinx/JSDoc)

Include specific commands or tool configurations for documentation automation (e.g., CI pipeline snippets, linting commands)

Add validation checkpoints with explicit verification steps (e.g., 'Run `npm run docs:lint` to validate formatting before committing')

Provide at least one complete input/output example showing what generated documentation should look like

Dimension	Reasoning	Score
Conciseness	The skill is reasonably efficient but includes some unnecessary framing ('You are a documentation expert...') and context that Claude already understands. The 'Use this skill when' and 'Do not use this skill when' sections add value but could be tighter.	2 / 3
Actionability	The instructions are vague and abstract ('Identify required doc types', 'Extract information from code', 'Generate docs'). No concrete code, commands, or executable examples are provided. The skill describes what to do rather than showing how to do it.	1 / 3
Workflow Clarity	Steps are listed in a sequence but lack validation checkpoints. 'Validate accuracy' is mentioned but not explained. No feedback loops for error recovery. The workflow is implicit rather than explicit with clear verification points.	2 / 3
Progressive Disclosure	The skill appropriately references an external resource ('resources/implementation-playbook.md') for detailed examples and templates, keeping the main skill file as an overview. References are one level deep and clearly signaled.	3 / 3
	Total	8 / 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) and lists several output types, but relies on buzzwords ('AI-powered analysis', 'industry best practices') instead of concrete actions. The critical weakness is the complete absence of explicit trigger guidance telling Claude when to select this skill. Additionally, the description uses second person voice ('You are') which violates the third-person requirement.

Suggestions

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

Replace vague phrases like 'AI-powered analysis and industry best practices' with specific actions like 'analyzes code structure, extracts function signatures, generates markdown documentation'

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) 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 explicit trigger guidance caps this at 2, but the 'what' is also weakened by vague language.	1 / 3
Trigger Term Quality	Includes some relevant keywords like 'API docs', 'architecture diagrams', 'user guides', 'technical references', but misses common variations users might say like 'README', 'docstrings', 'JSDoc', 'code comments', or 'document my code'.	2 / 3
Distinctiveness Conflict Risk	Documentation is a somewhat specific domain, but 'architecture diagrams' could overlap with diagramming skills, and 'technical references' is vague enough to conflict with general writing or code explanation 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: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: plugins/AI-Agents-Safe-Coding-Skills/skills/code-documentation-doc-generate/SKILL.md
Commit: 3b73fbb

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