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

46%

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%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 well-organized and concise but lacks executable guidance — instructions stay at a high level with no code, commands, or validation feedback loop, and its sole referenced file is not present in the bundle.

Suggestions

Add concrete, executable guidance: name specific tooling/commands (e.g. a doc-gen command, a linter invocation) or a worked example instead of generic bullets.

Turn 'validate accuracy' into an explicit validation-then-fix feedback loop with a checkpoint before producing final docs.

Either place implementation-playbook.md in the bundle (e.g. under references/) or remove the dangling reference so the cited path resolves.

Dimension	Reasoning	Score
Conciseness	The body is mostly lean and avoids explaining concepts Claude already knows, but the opening sentence and the 'Context' section restate the frontmatter description, so it could be tightened further.	3 / 5
Actionability	The Instructions are high-level hints ('Extract information from code, configs, and comments', 'Add automation (linting, CI)') with no concrete commands, tools, or executable examples, matching the 'minimal concrete guidance; high-level hints' anchor rather than the incomplete-but-executable level 3.	2 / 5
Workflow Clarity	A rough sequence exists (identify doc types, extract, generate, validate) but validation is only mentioned implicitly with no feedback loop or checkpoint, fitting the 'steps listed but validation gaps' anchor.	3 / 5
Progressive Disclosure	The body is well-sectioned and signals a one-level reference to 'resources/implementation-playbook.md', but no bundle directory exists and the referenced path is not under references/scripts/assets, so the reference cannot be verified against the actual bundle structure.	3 / 5
	Total	11 / 20 Passed

Description

50%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 conveys what the skill produces but omits any explicit trigger guidance and uses second-person voice, capping several dimensions at 3. Buzzword padding ('AI-powered analysis and industry best practices') adds no specificity.

Suggestions

Add an explicit 'Use when...' clause naming concrete triggers (e.g. 'Use when generating API docs from code, standardizing repo documentation, or building doc pipelines').

Rewrite in third person to match the rubric voice requirement ('Generates API docs, architecture diagrams, user guides, and technical references from code').

Replace 'AI-powered analysis and industry best practices' with concrete, user-natural trigger terms and synonyms.

Dimension	Reasoning	Score
Specificity	Lists concrete deliverables ('Generate API docs, architecture diagrams, user guides, and technical references') which is base-4 coverage, but the second-person voice 'You are a documentation expert' triggers the -1 specificity penalty, bringing it to 3.	3 / 5
Completeness	The 'what' is clear (generate documentation from code) but there is no 'Use when...' clause or equivalent trigger guidance, so completeness is capped at 3 per the rubric guideline.	3 / 5
Trigger Term Quality	Relevant keywords like 'API docs', 'architecture diagrams', and 'user guides' appear, but common variations and synonyms a user would naturally say (e.g. 'generate docs', 'document code', file extensions) are missing, matching the 'some relevant keywords but missing common variations' anchor.	3 / 5
Distinctiveness Conflict Risk	The code-to-documentation niche is somewhat specific, but 'comprehensive, maintainable documentation' is broad and could overlap with general writing or doc skills, fitting the 'somewhat specific but could still overlap' anchor rather than the clearly-distinct level 4.	3 / 5
	Total	12 / 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/code-documentation-doc-generate/SKILL.md
Commit: 57c135b

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