documentation-templates

Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.

Quality

54%

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

Quality

Content

52%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 provides a broad collection of documentation templates that are well-structured with tables and markdown examples, but suffers from being a monolithic reference rather than a well-organized skill with progressive disclosure. The templates are useful starting points but lack the concrete, filled-in examples that would make them truly actionable—most contain placeholder text rather than realistic content. The skill would benefit from splitting into separate files per template type and providing at least one fully realized example for each template.

Suggestions

Split the content into separate files (e.g., README_TEMPLATE.md, API_DOCS.md, ADR_TEMPLATE.md) and use SKILL.md as a concise overview with links to each.

Replace placeholder text like '[Minimum steps to run]' and '[Request and response example]' with concrete, realistic filled-in examples so templates are truly copy-paste ready.

Remove guidance Claude already knows, such as the 'When to Comment' table and the 'Structure Principles' section, to improve conciseness.

Add a brief workflow section explaining when and how to apply each template type (e.g., 'Use ADR template when making architectural decisions that affect multiple teams').

Dimension	Reasoning	Score
Conciseness	The content is mostly efficient with good use of tables and templates, but includes some unnecessary framing (e.g., 'Templates are starting points. Adapt to your project's needs') and the 'When to Comment' table states things Claude already knows. The overall structure is reasonable but could be tightened.	3 / 5
Actionability	Provides template structures that are somewhat actionable as copy-paste starting points, but most templates contain placeholder text like '[Minimum steps to run]' and '[Request and response example]' rather than concrete, filled-in examples. The guidance is more structural than executable.	3 / 5
Workflow Clarity	This is primarily a template/reference skill rather than a multi-step workflow, so the single-purpose exception applies. The content is well-sequenced with clear section ordering (README sections in priority order, comment guidelines with clear do/don't). No destructive operations are involved, so no validation checkpoints are needed.	4 / 5
Progressive Disclosure	All content is inlined in a single monolithic file with no references to supporting files. Given the breadth of topics (README, API docs, code comments, changelogs, ADRs, AI-friendly docs), this content would benefit significantly from being split into separate reference files with the SKILL.md serving as an overview with links.	2 / 5
	Total	12 / 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 its domain and lists several documentation types, providing moderate specificity. However, it lacks concrete action verbs describing what the skill does (e.g., generates, formats, validates) and completely omits a 'Use when...' clause, making it harder for Claude to know when to select this skill over others.

Suggestions

Add a 'Use when...' clause with trigger phrases like 'Use when the user asks to create or improve documentation, write a README, document an API, or add code comments'

Include concrete action verbs describing what the skill does, e.g., 'Generates README files, structures API documentation, formats code comments, and creates AI-friendly docs'

Add file extensions or format keywords like '.md', 'markdown', 'docstrings', 'JSDoc' to improve trigger term coverage

Dimension	Reasoning	Score
Specificity	Names the domain (documentation) and lists specific types (README, API docs, code comments, AI-friendly documentation), but doesn't describe concrete actions like 'generates', 'formats', or 'structures'. The actions are implied rather than stated.	3 / 5
Completeness	Has a reasonable 'what' (documentation templates and structure guidelines for various doc types) but completely lacks an explicit 'when' clause. There's no 'Use when...' guidance for Claude to know when to select this skill.	3 / 5
Trigger Term Quality	Includes several natural keywords users would say: 'README', 'API docs', 'code comments', 'documentation', 'templates'. Missing some variations like 'docstrings', 'JSDoc', 'markdown', '.md files', or 'developer docs'.	4 / 5
Distinctiveness Conflict Risk	Somewhat specific to documentation but could overlap with general coding skills, README generators, or API specification tools. The mention of 'AI-friendly documentation' adds some distinctiveness, but the broad scope of 'documentation' creates overlap 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-templates/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.