documentation-templates

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

Quality

83%

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

Quality

Content

85%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill body is a tight, well-organized catalog of documentation templates that respects the token budget and assumes Claude's competence. Its main weakness is that several templates retain bracketed placeholders instead of fully concrete, copy-paste-ready content, which caps actionability.

Suggestions

Fill in or replace bracketed placeholders (e.g., '[Minimum steps to run]', '[Request and response example]') with concrete minimal examples so templates are immediately copy-paste usable.

Consider adding one short completed worked example (e.g., a fully filled README or API endpoint) alongside the blank templates to bridge the gap between scaffold and executable output.

Dimension	Reasoning	Score
Conciseness	The body is lean and template-driven, presenting only reusable structures and brief purpose tables without explaining concepts Claude already knows; every section earns its place and verbosity is avoided.	3 / 3
Actionability	It provides concrete copy-paste-ready templates for README, API docs, JSDoc, changelogs, ADRs, and llms.txt, but several templates use placeholders like '[Minimum steps to run]' and '[Request and response example]' that leave key details unspecified, keeping it short of fully executable guidance.	2 / 3
Workflow Clarity	This is a simple template/reference skill with no multi-step destructive or batch process requiring validation; under the simple-skills note, the single action (apply the appropriate template) is unambiguous and the section ordering (priority order) provides a clear sequence.	3 / 3
Progressive Disclosure	No bundle files exist and none are referenced; the content is well-organized into clearly delineated numbered sections (README, API docs, comments, changelog, ADR, AI-friendly docs, principles) within a single file of modest size, satisfying the simple-skill threshold for progressive disclosure.	3 / 3
	Total	11 / 12 Passed

Description

82%

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 communicates a documentation-focused niche with natural trigger terms and an explicit when-to-use clause, giving it strong completeness and trigger quality. It is weaker on specificity (categories of output rather than concrete actions) and only moderately distinctive against related writing/doc skills.

Suggestions

Replace output-category nouns with concrete verbs (e.g., 'Generate README scaffolds, draft API endpoint docs, write JSDoc/TSDoc comments, and produce AI-friendly llms.txt files') to lift specificity toward level 3.

Add a distinguishing qualifier to reduce conflict risk, such as referencing reusable templates/structure guidelines specifically rather than documentation generally.

Dimension	Reasoning	Score
Specificity	Names the documentation domain and lists several concrete artifact types (README, API docs, code comments, AI-friendly documentation), but these are categories of output rather than concrete actions performed, so it falls short of 'multiple specific concrete actions' at level 3.	2 / 3
Completeness	The description states what the skill does (documentation templates and structure guidelines) and the explicit when_to_use field answers when Claude should use it, satisfying both 'what' and 'when' with explicit triggers.	3 / 3
Trigger Term Quality	Uses natural user vocabulary ('README', 'API documentation', 'code comments', 'AI-friendly documentation') that a user would plausibly say when asking for documentation help; the separate when_to_use reinforces these triggers.	3 / 3
Distinctiveness Conflict Risk	The documentation niche is reasonably specific, but 'documentation' is broad and could overlap with project-specific doc skills or general writing skills; triggers are not distinctive enough to fully rule out conflict.	2 / 3
	Total	10 / 12 Passed

Validation

81%

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

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 2 missing	Warning

	Total	13 / 16 Passed

Repository: vudovn/ag-kit
Path: .agents/skills/documentation-templates/SKILL.md
Commit: 04514f0

Reviewed: about 12 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.