Documentation and ADRs skill for Claude Code: record the why behind decisions

Addy Osmani's skill that makes Claude write decision records and docs that explain why, for teams making design choices.

Installs: 68.6K; on skills.sh
Stars: 112.6K; on GitHub
Updated: Nov 2026; last repo commit

When you make a significant technical decision or change a public API, Claude writes an architecture decision record (ADR) with status, date, context, decision, alternatives considered and consequences. It first looks for your existing convention, such as an ADR folder, numbering and heading style, and matches it. If none exists it uses docs/decisions/ with sequential numbers.

It also covers inline comments and gotchas, API docs, README structure, changelog upkeep, docs for agents (CLAUDE.md, spec files) and a prose review step. It bundles no scripts.

Good for

Teams choosing a framework, database or auth approach
Developers changing a public API who need docs and changelog entries
Anyone onboarding new engineers or agents to a codebase

Install documentation-and-adrs

Claude Code

Copy this prompt.

Install the documentation-and-adrs skill in Claude Code. Run this command:

npx skills add https://github.com/addyosmani/agent-skills --skill documentation-and-adrs

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

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.

Sections in SKILL.md

Overview
When to Use
Architecture Decision Records (ADRs)
When to Write an ADR
Match the existing convention first
ADR Template
Status
Date
Context
Decision
Alternatives Considered
MongoDB
SQLite
MySQL
Consequences
ADR Lifecycle

Key facts

Author: addyosmani (agent-skills pack)
Repository: addyosmani/agent-skills
Installs on skills.sh: 68,615 (2 Nov 2026)
GitHub stars (repo): 112,555 (2 Nov 2026)
License: MIT
Last commit (repo): 1 Nov 2026
What installs: SKILL.md only (1 file); bundles no scripts
Works in: Claude Code, Cursor, Codex, Copilot, Cline and more through the skills CLI; native Claude Code and Codex plugins
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass

What it includes

Framework, data model, auth, API style, hosting, costly-to-reverse choices
Claude writes an ADR for decisions that would be expensive to reverse.
Read · When to write an ADR
Detect ADR location, numbering and headings first
Claude looks at existing ADRs, project instructions and tooling such as an .adr-dir file, and reuses them. It flags conflicts instead of adding a second scheme.
Read · Match the existing convention
Status, Date, Context, Decision, Alternatives, Consequences
Default location is docs/decisions/ with sequential numbering, plus a lifecycle from Proposed to Superseded or Deprecated.
Try: “Write an ADR for choosing PostgreSQL over MongoDB.”
Write · ADR template
When to comment, when not to, document gotchas
Claude explains why, not what, and documents known traps.
Write · Inline documentation
Types first for TypeScript, OpenAPI for REST
Claude documents APIs inline with types, or with OpenAPI or Swagger.
Write · API documentation
README structure and changelog upkeep
Quick start, commands, architecture and contributing sections, and dated changelog entries.
Write · README and changelog
CLAUDE.md, spec files, ADRs and inline gotchas
Claude keeps project conventions where agents will read them.
Write · Documentation for agents
Check the writing without losing facts
Claude marks the details that must survive an edit, removes stock intros and promotional wording, and restores any lost caveat.
Write · Prose review

From the official docs

Questions

What does the Documentation and ADRs skill do?

It makes Claude write documentation that records why decisions were made. The main output is the architecture decision record, plus README, API and changelog guidance.

How do I install it?

Use the install box at the top of this page. The README installs the whole 25-skill pack with npx skills add addyosmani/agent-skills or a Claude Code plugin. This skill has no shared reference files, so a single-skill install is enough.

Where does it put ADRs?

It first matches any ADR folder, numbering and format already in your repo. Only if it finds none does it use docs/decisions/ with sequential numbers such as ADR-001.

When should I not use it?

The SKILL.md says not to document obvious code, not to add comments that restate the code, and not to write docs for throwaway prototypes.

Does it work in Cursor, Codex or Copilot?

Yes. The README documents a Codex plugin, the skills CLI for 70+ agents including Cursor, and manual setup for Cursor and Copilot. The slash commands (/spec, /plan, /build and so on) are Claude Code commands and do not appear in Copilot, where you invoke skills by name. The README does not describe a Claude app install.

Does it need an API key or an account?

No key or account is mentioned in the SKILL.md.

Is it safe to install?

It is low risk. It bundles no scripts. Claude writes documentation files (ADRs, README, changelog, OpenAPI) and code comments in your repo, so review the diff and work on a branch.

Information

updated Nov 2, 2026

Repository: addyosmani/agent-skills
Folder: skills/documentation-and-adrs

addyosmani/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 2

documentation-and-adrs SKILL.md · github.com
addyosmani/agent-skills README · github.com