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

58%

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

Quality

Content

50%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 content is well-structured and reasonably lean, but guidance stays at a high level without concrete commands, the main workflow is unsequenced, and the one referenced bundle file is missing. Tightening instructions and providing the playbook would raise all three weak dimensions.

Suggestions

Provide the missing 'resources/implementation-playbook.md' (or remove the reference) so the progressive-disclosure path actually resolves.

Turn the bulleted Instructions into a numbered sequence with explicit validation checkpoints instead of an unordered list.

Replace generic directives ('Generate docs with consistent terminology') with at least one concrete, copy-pasteable example or command.

Dimension	Reasoning	Score
Conciseness	The body is fairly lean, but it repeats the frontmatter description verbatim ('You are a documentation expert...') and carries an off-topic 'Compatibility and maintenance' alias paragraph that could be trimmed.	3 / 5
Actionability	Instructions are high-level directives ('Extract information from code, configs, and comments') with no concrete code or commands; the worked example adds some specifics but key execution details are missing.	3 / 5
Workflow Clarity	A rough sequence exists in the worked example with a validation step ('run the existing schema/doc build and the documented read-only call'), but the main Instructions are an unsequenced list and checkpoints are implicit rather than explicit.	3 / 5
Progressive Disclosure	Sections are well-organized and a single one-level reference is signaled ('resources/implementation-playbook.md'), but that file does not exist in the bundle, so the navigation path is broken.	3 / 5
	Total	12 / 20 Passed

Description

66%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 states what the skill produces and names concrete documentation types, but omits any explicit 'when to use' trigger guidance and leans on mild buzzword padding. Adding a 'Use when...' clause would lift its strongest deficit.

Suggestions

Add an explicit 'Use when generating documentation from code...' trigger clause so the 'when' is answered, not just the 'what'.

Drop the buzzword tail 'using AI-powered analysis and industry best practices' — it adds no actionable specificity.

Include a few natural synonyms users say (e.g. 'readme', 'reference docs') to broaden trigger coverage.

Dimension	Reasoning	Score
Specificity	Lists several concrete outputs — 'API docs, architecture diagrams, user guides, and technical references' — but pads with vague phrases ('AI-powered analysis and industry best practices'), so it stops short of a clean 5.	4 / 5
Completeness	The 'what' is clear (generate doc types from code) but there is no 'Use when...' clause or equivalent trigger guidance, which caps completeness at 3 per the rubric guideline.	3 / 5
Trigger Term Quality	Natural terms users would say are present ('documentation', 'API docs', 'architecture diagrams', 'user guides'), though common synonyms like 'readme' or 'reference docs' are missing.	4 / 5
Distinctiveness Conflict Risk	The code-to-documentation niche is fairly distinct, but the broad 'documentation' framing and the existence of a compatibility-aliased sibling skill ('documentation-generation-doc-generate') create minor overlap risk.	4 / 5
	Total	15 / 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: sickn33/agentic-awesome-skills
Path: skills/code-documentation-doc-generate/SKILL.md
Commit: b1aebac

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