documentation-and-adrs

Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase.

Quality

77%

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

Quality

Content

71%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.

Highly actionable body with excellent templates and a sensible convention-matching workflow, weakened by conceptual padding and a monolithic single-file structure that lacks progressive disclosure.

Suggestions

Trim the Overview philosophy and the 'Common Rationalizations' table to reduce explanation of concepts Claude already knows.

Move the ADR template, README structure, and API documentation examples into separate reference files (e.g. references/adr-template.md, references/readme-template.md) and link to them from SKILL.md.

Add an explicit validate-then-proceed feedback loop to the ADR-writing workflow (e.g. confirm the chosen location/numbering matches existing convention before writing the file).

Dimension	Reasoning	Score
Conciseness	Mostly efficient with useful templates, but the Overview philosophy and the 'Common Rationalizations' table restate documentation best practices Claude already knows and could be trimmed.	3 / 5
Actionability	Provides fully copy-paste-ready ADR, TSDoc, OpenAPI, README, and changelog templates covering the common cases with concrete examples.	5 / 5
Workflow Clarity	The 'Match the existing convention first' section gives a clear sequence with a conflict-surfacing checkpoint, the ADR lifecycle is explicit, and a closing verification checklist exists; minor validation gaps remain.	4 / 5
Progressive Disclosure	Well-organized with section headers, but at 285+ lines it inlines ADR/README/API templates that could live in separate reference files, and there are no external references to deeper material.	3 / 5
	Total	15 / 20 Passed

Description

83%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.

A strong description that clearly states capability and provides explicit, natural trigger conditions. It could be sharpened by adding ADR-specific synonyms and slightly tightening the 'documentation' breadth.

Dimension	Reasoning	Score
Specificity	Names the domain ('Records decisions and documentation') plus several concrete actions/scenarios (architectural decisions, changing public APIs, shipping features, recording context); minor coverage gaps keep it just below a 5.	4 / 5
Completeness	Explicitly answers both what ('Records decisions and documentation') and when ('Use when making architectural decisions, changing public APIs, shipping features...') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Natural trigger phrases like 'making architectural decisions', 'changing public APIs', and 'shipping features' map to what users would say, but it omits synonyms such as 'ADRs' or 'decision records'.	4 / 5
Distinctiveness Conflict Risk	The decision-record/architecture niche is clearly distinct, though the broad term 'documentation' creates minor overlap risk with general doc-writing skills.	4 / 5
	Total	17 / 20 Passed

Validation

100%

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

Validation for skill structure

No warnings or errors.

Repository: addyosmani/agent-skills
Path: skills/documentation-and-adrs/SKILL.md
Commit: df1edb2

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