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

57%

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

Quality

Content

53%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 is lean and well-structured with clear use/do-not-use guidance, but the Instructions are abstract rather than executable and the referenced playbook file is missing from the bundle.

Suggestions

Replace abstract Instructions with concrete, executable steps, e.g., specific commands or a worked example for extracting doc content from code and wiring linting/CI.

Add an explicit validation checkpoint with a feedback loop (validate output -> fix -> re-validate) since documentation accuracy is the stated goal.

Create the referenced `resources/implementation-playbook.md` or remove the broken reference so navigation does not dead-end.

Dimension	Reasoning	Score
Conciseness	The body is efficient and avoids explaining concepts Claude already knows, though the duplicated description line and the reworded 'Context' paragraph restate the same intent and could be trimmed.	4 / 5
Actionability	Instructions are high-level hints ('Extract information from code, configs, and comments', 'Add automation (linting, CI)') with no concrete commands, examples, or specific steps to execute, fitting the minimal-concrete-guidance anchor.	2 / 5
Workflow Clarity	A rough sequence exists (identify types, extract, generate, automate/validate) but validation is only implicit ('validate accuracy') with no explicit checkpoint or feedback loop.	3 / 5
Progressive Disclosure	Sections are well-organized and the single reference to `resources/implementation-playbook.md` is clearly signaled one level deep; however that file does not exist in the bundle, a minor organization gap keeping it below 5.	4 / 5
	Total	13 / 20 Passed

Description

61%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 clearly conveys the skill's purpose and concrete outputs but lacks an explicit trigger ('Use when...') clause and uses second-person voice, capping completeness and lowering specificity.

Suggestions

Add an explicit 'Use when...' trigger clause (e.g., 'Use when generating API docs, user guides, or architecture docs from a codebase') to lift completeness above 3.

Rewrite in third person ('Generates API docs...') instead of 'You are a documentation expert...' to avoid the specificity penalty.

Drop the buzzword tail 'using AI-powered analysis and industry best practices' in favor of a concrete trigger phrase with synonyms/file extensions.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ('Generate API docs, architecture diagrams, user guides, and technical references'), which would anchor at 4, but the second-person opening 'You are a documentation expert...' triggers the voice penalty reducing specificity by 1.	3 / 5
Completeness	Clearly states what it does (generates doc types from code) but has no 'Use when...' clause or explicit trigger guidance, which caps completeness at 3 per the rubric.	3 / 5
Trigger Term Quality	Includes natural terms a user would say ('documentation', 'API docs', 'user guides', 'architecture diagrams') with good coverage, though common synonyms and file extensions are absent.	4 / 5
Distinctiveness Conflict Risk	The 'documentation generation from code' niche is mostly distinct with only minor overlap risk against general doc-writing or code-analysis skills.	4 / 5
	Total	14 / 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-claude/skills/documentation-generation-doc-generate/SKILL.md
Commit: 57c135b

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