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

62%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

—

The risk profile of this skill

Fix and improve this skill with Tessl

tessl review fix ./skills/documentation-and-adrs/SKILL.md

The canonical home for this skill is documentation-and-adrs in addyosmani/agent-skills

Quality

Content

42%Scale 1-3

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

The skill provides excellent, concrete examples and templates (especially the ADR template and code commenting examples), making it highly actionable. However, it is far too verbose for a skill file — it explains many concepts Claude already understands (commenting best practices, README structure, changelog format) and packs everything into a single monolithic file rather than using progressive disclosure. The content would benefit greatly from being trimmed to essentials and split across referenced files.

Suggestions

Reduce the skill to ~50-80 lines covering the core workflow (when to document, ADR template location/format, verification checklist) and move detailed examples (API docs, README structure, changelog format, inline commenting guidance) into separate referenced files.

Remove the 'Common Rationalizations' table and 'Red Flags' section entirely — these explain basic software engineering philosophy that Claude already knows and consume significant tokens.

Trim the inline documentation section (good vs bad comments) to 2-3 lines of guidance rather than multiple code blocks showing obvious examples.

Add a clear sequential workflow: e.g., '1. Identify decision type → 2. Choose documentation artifact (ADR/inline/API doc) → 3. Write using template → 4. Verify with checklist' to improve workflow clarity.

Dimension	Reasoning	Score
Conciseness	The skill is extremely verbose at ~200+ lines, explaining many concepts Claude already knows well (what ADRs are, when to comment code, README structure, changelog format, what a TODO comment is). The 'Common Rationalizations' table and much of the inline documentation section teach basic software engineering principles rather than providing novel, actionable guidance. Significant token waste.	1 / 3
Actionability	The skill provides fully concrete, copy-paste-ready templates and examples: a complete ADR template with realistic content, TypeScript code examples showing good vs bad commenting, OpenAPI YAML, README structure, and changelog format. Every section includes executable or directly usable artifacts.	3 / 3
Workflow Clarity	The ADR lifecycle (PROPOSED → ACCEPTED → SUPERSEDED/DEPRECATED) is clearly stated, and the verification checklist at the end provides a good summary. However, there's no explicit step-by-step workflow for the overall documentation process — when to create which artifact, in what order, or how to validate that documentation is complete before shipping. The 'When to Use' section lists triggers but doesn't sequence them into a workflow.	2 / 3
Progressive Disclosure	All content is inlined in a single monolithic file with no references to supporting files. The ADR template, API documentation patterns, README structure, changelog format, and inline documentation guidance could each be separate reference files. For a skill this long, the lack of any content splitting or external references is a significant organizational weakness.	1 / 3
	Total	7 / 12 Passed

Description

82%Scale 1-3

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This is a solid description with a clear 'Use when' clause covering multiple trigger scenarios, and it uses appropriate third-person voice. Its main weakness is that the 'what' portion is somewhat vague—'records decisions and documentation' doesn't specify the concrete outputs (e.g., ADRs, changelogs, decision logs). The broad term 'documentation' also introduces some conflict risk with other documentation-focused skills.

Suggestions

Specify concrete outputs or formats, e.g., 'Creates Architecture Decision Records (ADRs), changelog entries, and design documents' instead of the generic 'Records decisions and documentation'.

Narrow the scope of 'documentation' to reduce overlap risk—clarify whether this covers ADRs specifically, design docs, or other specific artifact types.

Dimension	Reasoning	Score
Specificity	Names the domain (decisions and documentation) and mentions some specific scenarios (architectural decisions, API changes, shipping features), but doesn't list concrete actions beyond 'records'. It doesn't specify what formats, templates, or outputs are produced.	2 / 3
Completeness	Clearly answers both what ('Records decisions and documentation') and when ('Use when making architectural decisions, changing public APIs, shipping features, or when you need to record context that future engineers and agents will need'). The explicit 'Use when' clause with multiple trigger scenarios is well-formed.	3 / 3
Trigger Term Quality	Includes natural keywords users would say: 'architectural decisions', 'public APIs', 'shipping features', 'record context', 'documentation'. These are terms engineers naturally use when they need this kind of skill.	3 / 3
Distinctiveness Conflict Risk	The term 'documentation' is quite broad and could overlap with other documentation-related skills (e.g., API docs, README generation, code comments). However, the focus on 'architectural decisions' and 'context for future engineers' provides some distinctiveness.	2 / 3
	Total	10 / 12 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: finlay611/agent-skills
Path: skills/documentation-and-adrs/SKILL.md
Commit: fea75b1

Reviewed: 4 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.