documentation

Documentation generation workflow covering API docs, architecture docs, README files, code comments, and technical writing.

Quality

37%

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

Quality

Content

17%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 essentially a table of contents that delegates all actual work to other skills without providing any concrete, executable guidance itself. It is heavily padded with repetitive structure, vague action items, and categories Claude already understands. The workflow lacks validation steps, feedback loops, and any real substance that would help Claude generate documentation.

Suggestions

Replace vague action items (e.g., 'Extract API endpoints') with concrete, executable examples showing actual commands or code snippets for each documentation type.

Add validation/verification steps between phases, such as checking generated docs for completeness, validating OpenAPI specs with a linter, or verifying links before publishing.

Remove the 'Documentation Types' section entirely—Claude already knows what JSDoc comments, FAQs, and tutorials are. Use that space for actionable content instead.

Either provide the referenced bundle files (@docs-architect, @api-documenter, etc.) or replace the 'Copy-Paste Prompts' with inline, self-contained instructions that don't depend on external skills.

Dimension	Reasoning	Score
Conciseness	The content is heavily padded with repetitive structure across 8 phases, each following the same template of skills/actions/prompts. The 'Documentation Types' section explains categories Claude already knows (e.g., what JSDoc comments are, what FAQs are). The numbered action lists are generic and add little value (e.g., 'Identify documentation needs', 'Choose documentation tools').	2 / 5
Actionability	The skill provides no executable code, no concrete commands, and no specific examples. Every 'action' is a vague directive like 'Extract API endpoints' or 'Create C4 diagrams.' The 'Copy-Paste Prompts' are just 'Use @skill-name to do X' which are not actionable instructions—they delegate entirely to other skills without explaining what to actually do.	1 / 5
Workflow Clarity	While there is a rough 8-phase sequence, the steps within each phase are vague and lack any validation checkpoints or feedback loops. The 'Quality Gates' checklist at the end is a static list with no integration into the workflow phases. There's no guidance on what to do if documentation is incomplete or incorrect, and no verification steps between phases.	2 / 5
Progressive Disclosure	The skill references many sub-skills (e.g., @docs-architect, @api-documenter) but provides no actual links or file paths, and no bundle files exist to support them. The content is a monolithic document that could benefit from splitting phases into separate files. The references to other skills are not clearly signaled as navigable resources—they're just names.	2 / 5
	Total	7 / 20 Passed

Description

57%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 relevant documentation types, providing reasonable trigger terms. However, it lacks concrete actions (what it actually does with these doc types) and has no explicit 'Use when...' clause, which significantly limits its effectiveness for skill selection. The description reads more like a category label than actionable guidance for choosing this skill.

Suggestions

Add a 'Use when...' clause with explicit trigger phrases, e.g., 'Use when the user asks to generate, update, or review documentation, READMEs, API references, or code comments.'

Replace the passive 'covering' with concrete action verbs describing what the skill does, e.g., 'Generates API reference docs from code, creates architecture diagrams and docs, scaffolds README files, adds inline code comments and docstrings.'

Add synonym coverage for better trigger matching, such as 'docstrings', 'markdown', '.md files', 'developer docs', or 'inline documentation'.

Dimension	Reasoning	Score
Specificity	Names the domain (documentation generation) and lists several types of documentation (API docs, architecture docs, README files, code comments, technical writing), but these are categories rather than concrete actions. It says 'covering' but doesn't describe what actions are performed on them (e.g., generate, update, format, lint).	3 / 5
Completeness	Provides a clear 'what' (documentation generation workflow covering several doc types) but has no explicit 'when' clause. There is no 'Use when...' or equivalent trigger guidance, which per the rubric caps completeness at 3.	3 / 5
Trigger Term Quality	Includes several natural keywords users would say: 'API docs', 'architecture docs', 'README', 'code comments', 'technical writing'. Missing some variations like 'docstrings', 'JSDoc', 'markdown', 'documentation', or file extensions like '.md'. Good but not comprehensive.	4 / 5
Distinctiveness Conflict Risk	The description is somewhat specific to documentation generation, but 'technical writing' and 'code comments' are broad enough to overlap with general coding skills or writing assistance skills. The lack of a clear niche boundary increases conflict risk.	3 / 5
	Total	13 / 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: skills/documentation/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.