CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

documentation-generation-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.

44

Quality

56%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/documentation-generation-doc-generate/SKILL.md
SKILL.md
Quality
Evals
Security

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 brief with a reasonable step sequence and useful negative guidance, but it defers all concrete examples to a nonexistent `resources/implementation-playbook.md`, leaving the skill with vague, non-executable instructions and no working progressive-disclosure path. Validation is mentioned but never given a concrete mechanism.

Suggestions

Create `resources/implementation-playbook.md` (or remove the reference and inline a concrete example) so the deferred examples are actually reachable.

Add concrete executable guidance in the Instructions, e.g. specific doc-lint tools (markdownlint, vale), a CI snippet, or a sample documentation-plan template.

Make the validation step actionable: name the check ('run the doc linter and verify code references resolve against the source') instead of 'validate accuracy'.

DimensionReasoningScore

Conciseness

The body is short and mostly efficient, but the opening paragraph repeats the frontmatter description verbatim, the Context section ('The user needs automated documentation generation that extracts information...') restates the obvious, and phrases like 'using AI-powered analysis and industry best practices' add nothing — anchor 3 ('mostly efficient but includes some unnecessary explanation or could be tightened'). It is not 4 because the duplication and Context padding are more than minor single-instance trims.

3 / 5

Actionability

The Instructions are high-level directives with no concrete commands, tool names, templates, or examples ('Extract information from code, configs, and comments', 'Add automation (linting, CI)'), and the one pointer to concrete material — 'If detailed examples are required, open `resources/implementation-playbook.md`' — targets a file that does not exist anywhere in the bundle. This matches anchor 2 ('minimal concrete guidance; high-level hints but missing the specific steps to execute') and cannot reach 3 because even the deferred detail is unreachable.

2 / 5

Workflow Clarity

The Instructions list a sensible sequence (identify doc types → extract from code → generate → automate/validate) with 'validate accuracy' as an implicit checkpoint, matching anchor 3 ('steps listed but validation gaps; checkpoints missing or implicit'). It is not 4 because 'validate accuracy' names no mechanism or command, and not 2 because the steps are listed and correctly ordered with validation at least acknowledged.

3 / 5

Progressive Disclosure

Sections are well organized (Use when / Do not use / Instructions / Safety / Output Format / Resources) and the reference is clearly signaled one level deep, but the referenced path `resources/implementation-playbook.md` does not exist — the bundle contains no resources/, references/, scripts/, or assets/ directories — so the disclosure path is broken and Claude would open a missing file. Scoring against the actual bundle structure, this lands at anchor 3 ('some structure; references present but not effectively usable') rather than 4.

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 clearly names the domain and multiple concrete documentation artifacts, but it lacks any 'Use when...' trigger clause (capping completeness at 3), uses second-person persona voice with buzzword filler ('AI-powered analysis', 'industry best practices'), and has moderate overlap risk with adjacent writing/doc skills. It sits at the scale midpoint overall.

Suggestions

Add an explicit trigger clause, e.g. 'Use when generating API docs, user guides, or architecture documentation from a codebase, or when building documentation automation/CI pipelines.'

Rewrite in third person and drop the buzzwords: 'Generates API docs, architecture diagrams, user guides, and technical references from source code, configs, and comments.'

Include natural synonyms users would actually say ('docs', 'README', 'document this code') to widen trigger coverage and distinguish it from generic writing skills.

DimensionReasoningScore

Specificity

The description lists several concrete outputs ('Generate API docs, architecture diagrams, user guides, and technical references'), fitting anchor 4 ('lists several specific actions; minor gaps'), but it is written in second person ('You are a documentation expert') and padded with fluff ('AI-powered analysis', 'industry best practices'), and the guideline mandates a 1-point specificity reduction for non-third-person voice, bringing it to 3. It is not a 2 because the domain and multiple concrete artifacts are clearly named, unlike 'Processes PDF files'.

3 / 5

Completeness

The 'what' is clearly stated (generate API docs, architecture diagrams, user guides, technical references from code), but the 'when' is entirely absent — there is no 'Use when...' clause or equivalent trigger guidance, which caps completeness at 3 per the judging guidelines. It is above 2 because the 'what' is concrete and multi-faceted, not vague.

3 / 5

Trigger Term Quality

It contains relevant natural terms users would say ('API docs', 'architecture diagrams', 'user guides', 'technical references'), but misses common variations and synonyms such as 'docs', 'README', 'code documentation', or 'document this codebase' — matching anchor 3 ('some relevant keywords but missing common variations or synonyms'). It falls short of 4 because coverage of natural phrasing is thin alongside the buzzword filler.

3 / 5

Distinctiveness Conflict Risk

The 'from code' scoping and named artifact types give it a moderately distinct niche, but with no trigger boundary it could overlap with README-writing, general technical-writing, or code-explanation skills whenever 'documentation' is mentioned — anchor 3 ('somewhat specific but could still overlap with similar skills'). It is not 4 because nothing in the description disambiguates it from those closely related skills.

3 / 5

Total

12

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

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

skills/documentation-generation-doc-generate/SKILL.md

Reviewed

Table of Contents

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.