documentation-and-adrs

Records decisions and documentation. Use when you need to document an architecture decision (ADR) or the reasoning behind a design choice, when changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase.

Quality

70%

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

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

A highly actionable, well-structured documentation skill whose templates and verification checklist leave no ambiguity about what to produce. Its main costs are motivational/boilerplate content Claude does not need and secondary templates inlined that would fit better in reference files.

Suggestions

Cut or compress the 'Common Rationalizations' table and the README quick-start boilerplate (clone/install/run command rows) — Claude already knows these; keep only the required section checklist.

Move the README structure, changelog format, and OpenAPI/TSDoc examples into a references/ file, keeping SKILL.md as the ADR-focused overview with clearly signaled one-level-deep links.

Extend the convention-conflict guidance with one concrete recovery step (e.g. ask the user which convention to follow, or record the conflict in the new ADR's Context section) to close the workflow's only validation gap.

Dimension	Reasoning	Score
Conciseness	Mostly efficient, but the 'Common Rationalizations' motivational table, the generic README boilerplate ('npm install', 'npm run dev' command table), and the changelog example restate knowledge Claude already has and could be cut or tightened without losing guidance.	3 / 5
Actionability	Fully concrete and copy-paste ready: a complete worked ADR template (PostgreSQL with per-alternative rejection reasons), good/bad comment and gotcha examples, TSDoc and OpenAPI snippets, and a closing verification checklist cover the common cases.	5 / 5
Workflow Clarity	There is no numbered end-to-end sequence, but the 'match the existing convention first' decision procedure, the PROPOSED → ACCEPTED → SUPERSEDED lifecycle, and the final verification checklist give clear checkpoints; a minor gap is that conflict handling stops at 'surface the conflict' without a recovery step.	4 / 5
Progressive Disclosure	The single-file skill is well sectioned and navigable, and the inline ADR template is core content that belongs in SKILL.md; the README, changelog, and API documentation templates are secondary material that could be moved to references/ files.	4 / 5
	Total	16 / 20 Passed

Description

66%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 solid description with an explicit and multi-triggered 'Use when' clause in correct third-person voice. Its weaknesses are a vague opening capability statement and overly broad triggers ('shipping features') that create over-triggering risk.

Suggestions

Replace the generic opener 'Records decisions and documentation' with the skill's concrete outputs, e.g. 'Writes ADRs, inline rationale comments, README and API documentation, and changelogs' so the what-half is as specific as the when-half.

Trim or narrow the 'when changing public APIs, shipping features' trigger to significant/irreversible changes (e.g. 'when making an expensive-to-reverse architectural choice or changing a public API') to reduce conflict with routine feature work.

Dimension	Reasoning	Score
Specificity	The leading capability statement 'Records decisions and documentation' is generic; the only concrete actions ('document an architecture decision (ADR)', 'the reasoning behind a design choice') appear embedded in the when-clause rather than as stated capabilities, matching the anchor for domain-plus-1-2-concrete-actions rather than the several-specific-actions anchor.	3 / 5
Completeness	Both halves exist: 'Records decisions and documentation' answers what, and an explicit 'Use when...' lists multiple concrete triggers; it falls short of the top anchor because the what-statement is vague and does not preview the README, changelog, and API documentation work the body actually covers.	4 / 5
Trigger Term Quality	Good natural triggers are present ('architecture decision (ADR)', 'design choice', 'public APIs', 'shipping features'), but common variations for the skill's full scope — README, changelog, code comments, API docs — are absent, so coverage is good rather than comprehensive.	4 / 5
Distinctiveness Conflict Risk	ADR and design-reasoning triggers are distinctive, but 'when changing public APIs, shipping features' is broad enough to fire on routine feature work where this skill is not wanted, leaving real overlap risk with general coding and code-review skills.	3 / 5
	Total	14 / 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: 2686b62

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.