documentation-generation-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

38%

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/documentation-generation-doc-generate/SKILL.md

Quality

Content

36%Scale 1-5

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

This skill is too abstract and lacks actionable guidance. The instructions read as a high-level checklist without concrete commands, code examples, or specific tools. The workflow is vague with no validation steps, and the referenced playbook file is not provided, making it impossible to verify the progressive disclosure actually delivers value.

Suggestions

Add concrete, executable examples of documentation generation (e.g., specific commands for tools like Sphinx, TypeDoc, or JSDoc with configuration snippets)

Define explicit validation steps in the workflow, such as running a doc linter or checking for broken links after generation

Replace vague instructions like 'Extract information from code' with specific techniques (e.g., parsing docstrings, reading OpenAPI specs, analyzing type annotations)

Provide the referenced `resources/implementation-playbook.md` or inline at least one complete worked example showing input code and expected documentation output

Dimension	Reasoning	Score
Conciseness	The skill includes some unnecessary sections like 'Context' that restates what Claude already knows, and the 'Use this skill when' / 'Do not use this skill when' sections add moderate padding. However, it's not severely verbose.	3 / 5
Actionability	The instructions are high-level and vague ('Identify required doc types', 'Extract information from code') without any concrete commands, code examples, or specific tooling. There's nothing executable or copy-paste ready.	2 / 5
Workflow Clarity	There's a rough sequence in the Instructions section but steps are poorly defined with no specific commands, no validation checkpoints, and no feedback loops. 'Validate accuracy' is mentioned but not explained how.	2 / 5
Progressive Disclosure	References `resources/implementation-playbook.md` for detailed examples, which is appropriate progressive disclosure. However, no bundle files are provided to verify the reference exists, and the main content itself is too thin to justify the split—it feels like the substance is deferred rather than summarized.	3 / 5
	Total	10 / 20 Passed

Description

41%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 identifies the domain and lists several documentation output types, but suffers from vague buzzwords ('AI-powered analysis', 'industry best practices') and uses second-person/role-based framing ('You are a documentation expert') instead of third-person action descriptions. It critically lacks a 'Use when...' clause, making it harder for Claude to know when to select this skill over others.

Suggestions

Add an explicit 'Use when...' clause with trigger phrases like 'document my code', 'generate API docs', 'create a README', 'write technical documentation', or 'explain this codebase'.

Replace vague filler phrases like 'AI-powered analysis and industry best practices' with concrete actions such as 'parses source code to extract function signatures, class hierarchies, and module structures'.

Rewrite in third person voice (e.g., 'Generates API documentation, architecture diagrams, and user guides from source code') instead of the current role-based 'You are...' framing.

Dimension	Reasoning	Score
Specificity	Names the domain (documentation from code) and lists several outputs (API docs, architecture diagrams, user guides, technical references), but the actions are more about outputs than concrete actions. 'AI-powered analysis and industry best practices' is vague filler.	3 / 5
Completeness	Has a reasonable 'what' (generate various documentation types from code) but completely lacks a 'when' clause or any explicit trigger guidance. Per rubric guidelines, missing 'Use when...' caps completeness at 3, and the 'what' is only moderately clear, placing this at 2.	2 / 5
Trigger Term Quality	Includes some relevant keywords like 'API docs', 'architecture diagrams', 'user guides', 'technical references', and 'documentation', but misses common natural phrases users would say like 'README', 'docstrings', 'JSDoc', 'swagger', 'openapi', or 'document my code'.	3 / 5
Distinctiveness Conflict Risk	The documentation focus provides some specificity, but 'documentation expert' is broad enough to overlap with general writing skills, README generators, or code commenting tools. The mention of specific output types (API docs, architecture diagrams) helps somewhat but doesn't fully distinguish it.	3 / 5
	Total	11 / 20 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/documentation-generation-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.