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?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/documentation-and-adrs/SKILL.md

Quality

Content

42%

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

This skill is highly actionable with excellent concrete templates and examples (ADR, README, changelog, API docs), but it suffers from significant verbosity — much of the content covers software engineering best practices Claude already knows (commenting philosophy, README conventions, changelog format). The monolithic structure with no progressive disclosure makes it token-expensive, and the workflow guidance lacks explicit sequencing and feedback loops for the documentation creation process itself.

Suggestions

Cut the content by 50-60%: remove the 'Common Rationalizations' table, the 'Red Flags' list, the 'When NOT to Comment' section, and explanatory prose about why documentation matters — Claude already knows these things.

Extract the ADR template, README template, and API documentation patterns into separate referenced files (e.g., templates/adr-template.md, templates/readme-template.md) and keep SKILL.md as a concise overview with navigation links.

Add an explicit workflow sequence for the documentation process: e.g., 1) Identify decision type → 2) Choose template → 3) Draft → 4) Run verification checklist → 5) If gaps found, iterate.

Remove the 'Documentation for Agents' section — it's meta-commentary about why docs help agents rather than actionable guidance for creating documentation.

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 practices rather than providing novel, actionable guidance.	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 comments, an OpenAPI spec snippet, a README template, and a changelog format. All examples are executable and specific.	3 / 3
Workflow Clarity	The ADR lifecycle is clearly sequenced (PROPOSED → ACCEPTED → SUPERSEDED/DEPRECATED), and there's a verification checklist at the end. However, there's no explicit workflow for the documentation process itself — no step-by-step sequence for when/how to create documentation during feature development, and the verification checklist lacks feedback loops (e.g., what to do if checks fail).	2 / 3
Progressive Disclosure	All content is 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%

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 natural language engineers would actually say. Its main weakness is that the 'what' portion is somewhat vague — 'Records decisions and documentation' doesn't specify the concrete output format or actions (e.g., ADRs, decision logs, changelogs). The broad term 'documentation' also introduces some overlap risk with other skills.

Suggestions

Make the 'what' more specific by listing concrete outputs, e.g., 'Creates Architecture Decision Records (ADRs), changelog entries, and design documentation'

Narrow 'documentation' to reduce conflict risk — specify the type of documentation (e.g., 'decision records', 'design docs') to distinguish from general documentation skills

Dimension	Reasoning	Score
Specificity	Names the domain (decisions and documentation) and lists some actions (architectural decisions, changing public APIs, shipping features, recording context), but doesn't describe concrete actions like 'create ADR files' or 'write changelog entries' — it's more about when to use it than what specific actions it performs.	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'). Has an explicit 'Use when' clause with multiple trigger scenarios.	3 / 3
Trigger Term Quality	Includes strong natural trigger terms 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). However, the focus on 'architectural decisions' and 'context for future engineers' provides some distinctiveness. The word 'Records' helps narrow it but 'documentation' alone is a conflict risk.	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: addyosmani/agent-skills
Commit: c076972

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.