Name: documentation
Rating: 51.2 (1 reviews)
Author: administrakt0r

documentation

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

Quality

56%

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

The canonical home for this skill is documentation in administrakt0r/AI-Agents-Safe-Coding-Skills

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 lays out a clearly sequenced eight-phase documentation workflow with copy-paste prompts, but it relies on generic action steps, lacks per-phase validation checkpoints, and keeps all content inline with no progressive disclosure to supporting files.

Suggestions

Replace generic per-phase action lists with concrete, executable steps (specific commands, tool invocations, or templates).

Add per-phase validation checkpoints (e.g., verify generated docs compile / links resolve before moving to the next phase) rather than only a terminal Quality Gates checklist.

Move per-phase detail (skills, prompts, examples) into one-level-deep reference files and link them from a concise overview to improve progressive disclosure.

Dimension	Reasoning	Score
Conciseness	Content is list-based rather than explaining concepts Claude already knows, but each phase repeats a generic five-step action list and the 'Documentation Types' section re-covers ground the phases already addressed, so it could be tightened.	3 / 5
Actionability	Concrete copy-paste prompts ('Use @docs-architect to plan documentation structure') are provided, but the per-phase action steps are generic ('Identify documentation needs', 'Choose documentation tools') with no executable specifics or tool commands.	3 / 5
Workflow Clarity	The eight phases are clearly sequenced with skills-to-invoke and actions, but validation exists only as a terminal 'Quality Gates' checklist rather than per-phase checkpoints, leaving sequence validation implicit.	3 / 5
Progressive Disclosure	The body is well-sectioned but ~250 lines all inlined in SKILL.md with no bundle files; phase-specific detail that could live in one-level-deep references is not split out or signaled.	3 / 5
	Total	12 / 20 Passed

Description

62%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 workflow covers with a good spread of natural trigger terms, but it omits any explicit 'when to use' guidance and is broad enough to overlap with the individual documentation skills it orchestrates.

Suggestions

Add an explicit 'Use when...' clause naming concrete user triggers (e.g., 'Use when generating API docs, README files, or architecture diagrams from a codebase').

Narrow or disambiguate the scope to reduce overlap with the individual doc skills it invokes, or frame it explicitly as the orchestrating bundle.

Include common synonyms/file cues (e.g., 'docs', '.md', 'JSDoc/TSDoc', 'OpenAPI') to improve trigger-term coverage.

Dimension	Reasoning	Score
Specificity	Names the documentation domain and lists several concrete output types ('API docs, architecture docs, README files, code comments, and technical writing'), though these are categories rather than concrete operations, keeping it just below a 5.	4 / 5
Completeness	Provides a clear 'what' (documentation generation workflow covering the listed doc types) but has no 'Use when...' clause or equivalent explicit trigger guidance, which per the rubric caps completeness at 3.	3 / 5
Trigger Term Quality	Includes natural terms users would say ('API docs', 'README files', 'architecture docs', 'code comments') but misses generic synonyms like 'documentation' and 'docs' and file extensions, so not comprehensive enough for a 5.	4 / 5
Distinctiveness Conflict Risk	Scoped to documentation but spans many sub-domains (API, architecture, README, code comments, wiki, changelog) that are individually addressed by other skills, creating real overlap risk.	3 / 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/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.