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

55%

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 ./.agent/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 body is well-structured and reasonably lean, but it provides only abstract instructions with no executable code or tools, and its detail references are dangling/inconsistent because the referenced files are not bundled.

Suggestions

Add at least one concrete, executable example — e.g. a specific doc-gen command or a minimal code snippet using a named tool — to lift actionability.

Sequence the Instructions as a numbered workflow with an explicit validation checkpoint (e.g. 'After generating, verify docs match code by running X') instead of a flat bullet list.

Resolve the broken references: bundle the playbook at a single path and update both the Resources and Knowledge Modules entries to point to that same existing file.

Dimension	Reasoning	Score
Conciseness	The body is short and bullet-driven with lean sections; the main over-explanation is the intro paragraph that restates the description verbatim and the 'AI-powered ... industry best practices' padding, which are minor instances that could be trimmed.	4 / 5
Actionability	Instructions are high-level directives ('Extract information from code, configs, and comments', 'Add automation (linting, CI)') with no named tools, commands, or executable examples — concrete, copy-paste-ready guidance is missing, matching the 'minimal concrete guidance' anchor.	2 / 5
Workflow Clarity	Steps exist as a bulleted list with an implied order, but there is no numbered sequence and 'validate accuracy' is only an implicit checkpoint with no feedback loop, fitting the 'sequence present but checkpoints missing or implicit' anchor.	3 / 5
Progressive Disclosure	Sections are clearly organized and references are signaled (Resources + 'open ... if detailed examples required'), but neither referenced file exists and the same playbook is pointed to via two inconsistent paths (resources/ vs sub-skills/), so navigation does not actually resolve.	3 / 5
	Total	12 / 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 names concrete doc deliverables and good natural trigger terms, but it omits any explicit 'when to use' trigger guidance and uses second-person voice with buzzword padding, capping completeness and lowering specificity.

Suggestions

Add an explicit 'Use when...' clause naming concrete triggers, e.g. 'Use when generating API docs, architecture diagrams, user guides, or technical references from a codebase, or when standardizing documentation across a repository.'

Rewrite in third person ('Generates ... from code') and drop the 'You are a documentation expert' framing to avoid the voice penalty.

Remove the 'AI-powered analysis and industry best practices' filler in favor of synonyms/extensions users actually say (e.g. 'READMEs, docstrings, .md files').

Dimension	Reasoning	Score
Specificity	Lists several concrete deliverables ('Generate API docs, architecture diagrams, user guides, and technical references'), which would merit a 4, but the second-person opener 'You are a documentation expert' triggers the voice penalty reducing specificity by one point, and 'AI-powered analysis and industry best practices' is vague padding.	3 / 5
Completeness	The 'what' is clearly stated (generate API docs, architecture diagrams, user guides, technical references from code), but there is no 'Use when...' or equivalent trigger clause, which per the rubric caps completeness at 3.	3 / 5
Trigger Term Quality	Natural terms users would say are present ('API docs', 'architecture diagrams', 'user guides', 'technical references', 'documentation'), but coverage lacks synonyms and file extensions (no 'README', 'docstrings', '.md'), so it stops short of a 5.	4 / 5
Distinctiveness Conflict Risk	The 'documentation from code' framing plus the four named deliverable types carve a mostly distinct niche with only minor overlap risk against general writing/formatting skills.	4 / 5
	Total	14 / 20 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 1 missing	Warning

	Total	14 / 16 Passed

Repository: Dokhacgiakhoa/Agent-Skills-4-Vibe-Coding-CLI
Path: .agent/skills/code-documentation-doc-generate/SKILL.md
Commit: c4a059b

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