architecture-decision-records skill (wshobson): write ADRs with your agent

A skill that helps your agent write and maintain Architecture Decision Records with ready templates.

Installs: 23.3K; on skills.sh
Stars: 42.1K; on GitHub
Files: 2; besides SKILL.md
Updated: Oct 2026; last repo commit

architecture-decision-records helps your agent draft an ADR, a short document with context, decision and consequences. It triggers when you document a technical decision, review past choices or set up a decision process.

The SKILL.md covers when to write an ADR, a status lifecycle, a docs/adr folder layout, an index template and a review checklist. Before drafting, the agent reads one of two reference files holding five templates. Its Automation section shows adr-tools commands that need brew install adr-tools.

Good for

Tech leads recording architecture and technology choices
Teams that want a numbered docs/adr folder and a review process
Engineers deprecating a technology or writing an RFC

Install architecture-decision-records

Claude Code

Copy this prompt.

Install the architecture-decision-records skill in Claude Code. Run this command:

npx skills add https://github.com/wshobson/agents --skill architecture-decision-records

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

Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.

Sections in SKILL.md

When to Use This Skill
Core Concepts
1. What is an ADR?
2. When to Write an ADR
3. ADR Lifecycle
ADR Management
Directory Structure
ADR Index (README.md)
Index
Creating a New ADR
ADR Status
Automation (adr-tools)
Review Process
ADR Review Checklist
Before Submission
During Review

Key facts

Author: wshobson (agents repo)
Repository: wshobson/agents (plugins/documentation-generation/skills/architecture-decision-records)
Installs on skills.sh: 23,325 as of 2026-11-02
GitHub stars: 42,081 for the whole wshobson/agents repo, 2026-11-02
License: MIT (as detected by GitHub)
Last commit to the repo: 2026-10-30
What is inside: 3 files including SKILL.md (two reference files holding 5 templates)

What it includes

Table of what deserves an ADR and what to skip
Write one for a new framework, database choice, API design pattern, security architecture or integration pattern. Skip minor upgrades, bug fixes and configuration changes.
Read · When to write an ADR
Proposed, Accepted, Deprecated, Superseded or Rejected
Defines the five statuses an ADR moves through.
Read · ADR lifecycle
docs/adr with numbered files and a README index
Suggests files like 0001-use-postgresql.md, a template.md and a README.md index with a status table.
Try: “Set up a docs/adr folder and write ADR 0001 for choosing PostgreSQL.”
Write · Directory structure and index
adr init, adr new, adr generate toc, adr link
Shows adr-tools commands for creating, superseding and linking ADRs. The skill lists brew install adr-tools first.
Runs code · adr-tools automation
Before submission, during review, after acceptance
A checklist covering context, options, trade-offs, reviewers, security and cost, and index and ticket updates after acceptance.
Read · Review checklist
MADR, lightweight and Y-statement ADRs
Read from decision-templates.md before drafting a standard, lightweight or Y-statement ADR.
Read · Templates 1 to 3
Deprecation ADR and RFC-style document
Read from deprecation-rfc-templates.md before drafting a deprecation ADR or an RFC.
Read · Templates 4 and 5

From the official docs

Permissions

Low risk

The agent can create and edit ADR files in your repo and may run adr-tools commands. Review new files before you commit them.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

The skill lists a brew install step for adr-tools
The Automation section starts with brew install adr-tools. Install it yourself only if you want it, and read the command before you approve it.

Technical details

Scopes	May create or edit files under docs/adr May run adr-tools commands from the Automation section

Questions

What does the architecture-decision-records skill do?

It guides your agent through writing Architecture Decision Records. It gives the agent a lifecycle, a folder layout, a review checklist and five templates (MADR, lightweight, Y-statement, deprecation and RFC).

How do I install it in Claude Code, the Claude app or Codex?

Use the install box at the top of this page. The SKILL.md does not name which clients it works in, and the repo is a collection of plugins, so check the repo README for its own install routes.

Do I need adr-tools?

No. The SKILL.md lists adr-tools as an optional automation route, starting with brew install adr-tools. The templates and checklist work without it.

Does it need an API key?

None is mentioned in the SKILL.md or the two reference files.

Is it safe to install?

It is three markdown files and no scripts. The agent may create or edit files under docs/adr, and it may run adr-tools commands if you have them. Review new files before you commit them.

Can the agent change an accepted ADR?

The skill says not to. Its Don'ts say to write a new ADR that supersedes the old one and to update the old one's status.

Information

updated Nov 2, 2026

Repository: wshobson/agents
Folder: plugins/documentation-generation/skills/architecture-decision-records

wshobson/agents skills.sh

Sources

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

Show all 3

architecture-decision-records SKILL.md · github.com
decision-templates.md · github.com
deprecation-rfc-templates.md · github.com