Guide · Agent skill
How to use the Architecture Decision Records agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The architecture-decision-records skill teaches an AI agent the standard structure for Architecture Decision Records: short documents that capture the context behind a technical choice, the decision itself, and its consequences. This guide explains what the skill does, how to install it from the ZIP on this page, how to trigger it with everyday requests, and what to watch for. By the end you will be able to ask an agent to draft, index, and review ADRs for your team.
Architecture Decision Recordswshobson/agents · MIT Download the skill Quick start
- 1Download and unzip. Download the ZIP for architecture-decision-records from this page and unzip it. You should see a folder containing SKILL.md and a references folder.
- 2Place the folder. Move the folder to ~/.claude/skills/ for personal use, or to .claude/skills/ inside a project. Alternatively, upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Make a decision request. Describe a significant technical decision in plain language, including the options you considered and the constraints.
- 4Choose a format. Ask for a standard, lightweight, or Y-statement ADR. The agent reads the matching template before drafting.
- 5Review and link. Run the review checklist with your team and link any related ADRs.
- 6Update the index. After acceptance, add the ADR to docs/adr/README.md and mark its status.
What the skill makes the agent do
An Architecture Decision Record (ADR) is a short document that records why a significant technical decision was made. The skill tells the agent to capture three things: the context (why a decision was needed), the decision (what was chosen), and the consequences (what follows from it).
Once installed, the agent can draft an ADR in a standard (MADR-style), lightweight, or Y-statement format. It can also set up an ADR folder and index, apply a review checklist, and track each record through its lifecycle: Proposed, Accepted, Deprecated, Superseded, or Rejected. The skill also covers deprecation ADRs and RFC-style proposals, using separate reference templates.
- Draft standard, lightweight, or Y-statement ADRs
- Create a docs/adr folder with an index (README.md)
- Walk through a before-submission, review, and after-acceptance checklist
- Cover deprecation ADRs and RFC-style proposals
Install the skill from the ZIP
Download the ZIP for this skill from this page and unzip it. The skill is a folder named architecture-decision-records that contains SKILL.md, references/decision-templates.md, and references/deprecation-rfc-templates.md. Put that folder in one of two places, depending on how you want to use it.
For a personal install that works across your projects, place the folder in ~/.claude/skills/. For a single project, place it in the project's .claude/skills/ folder so that it applies only there. Alternatively, in the Claude apps, open Settings → Capabilities → Skills and upload the skill there.
- Personal: ~/.claude/skills/architecture-decision-records/
- Project only: .claude/skills/architecture-decision-records/ inside your repository
- Claude apps: Settings → Capabilities → Skills, then upload
Trigger the skill with natural requests
You do not need a special command. Describe the task in plain language and the agent will load the skill when the request matches its description: documenting a significant technical decision, reviewing past architectural choices, or setting up a decision process.
Name the decision and the format you want. The more context you give, such as the options you considered and the constraints, the better the draft will be.
- "Write an ADR for choosing PostgreSQL as our primary database. We considered MySQL and MongoDB."
- "Draft a lightweight ADR for our caching strategy."
- "Set up an ADR folder for this repo with an index and template."
- "Write a Y-statement for why we moved to a monorepo."
- "Help me write a deprecation ADR to retire MongoDB user profiles."
- "Review our ADRs and check which ones are still accepted versus superseded."
Use the optional adr-tools automation
The skill shows command-line automation using adr-tools, which is optional. The source installs it with Homebrew and then uses the adr command to create the ADR directory, new records, supersession, a table of contents, and links between records. Run these commands yourself or ask the agent to show you them; the skill does not need them to write ADRs.
The skill's example writes the table of contents to a separate file so that the hand-written index and guidelines in README.md are not overwritten.
- brew install adr-tools installs the tool (Homebrew required)
- adr init docs/adr initializes the ADR directory
- adr new "Title" creates a new ADR
- adr new -s 3 "Title" creates an ADR that supersedes ADR 3
- adr generate toc > docs/adr/toc.md writes a table of contents to its own file
- adr link 2 "Complements" 1 "Is complemented by" links related records
brew install adr-tools
adr init docs/adr
adr new "Use PostgreSQL as Primary Database"
adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"
adr generate toc > docs/adr/toc.md
adr link 2 "Complements" 1 "Is complemented by"Follow the review checklist and lifecycle
The skill includes a review checklist with three stages: before submission, during review, and after acceptance. It asks you to confirm that the context is clear, all viable options were considered, pros and cons are honest, and related ADRs are linked. During review it suggests consulting affected teams and assessing reversibility. After acceptance it reminds you to update the index, notify the team, and create implementation tickets.
Each ADR moves through the lifecycle statuses. Accepted records should not be edited. To change a decision, write a new ADR that supersedes the old one and mark the old one accordingly.
- Proposed: under discussion
- Accepted: decision made, implementing
- Deprecated: no longer relevant
- Superseded: replaced by another ADR
- Rejected: considered but not adopted
What it needs and what to watch for
The skill itself runs no scripts and makes no network calls. Its workflow assumes your decisions live in a docs/adr folder in version-controlled documentation and that changes are reviewed through pull requests. Only the optional adr-tools automation needs anything installed, and that is installed via Homebrew.
Do not use the skill for minor version upgrades, bug fixes, or routine configuration changes, which the skill says do not need an ADR. It is also not meant for non-technical decisions.
- No scripts are run by the skill
- No network access is used by the skill
- adr-tools is optional and installed via Homebrew
- Assumes a docs/adr folder and pull request review
What people use it for
- Recording why your team chose PostgreSQL over MongoDB, with the options and trade-offs written down
- Onboarding a new engineer by generating a readable index of past architecture decisions
- Retiring an old technology with a deprecation ADR that includes a migration plan
- Proposing a new API design pattern through an RFC-style document for team review
Frequently asked questions
Is the architecture decision records skill free?
The skill is published under the MIT licence, as stated on this page. The optional adr-tools automation is a separate tool installed via Homebrew, so check its own terms if you use it.
Do I need to install anything to use it?
No. The skill itself runs no scripts and uses no network. Installing adr-tools is optional and only needed if you want the command-line automation shown in the skill.
Where do I put the skill folder?
Use ~/.claude/skills/ for personal use across projects, or .claude/skills/ inside a project for that project only. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
Does the agent write ADRs without any command-line tools?
Yes. The skill describes the structure, templates, and review process, so the agent can draft ADRs directly. adr-tools only automates tasks such as creating numbered files and generating a table of contents.
Why does the agent say a small change does not need an ADR?
The skill lists minor version upgrades, bug fixes, implementation details, routine maintenance, and configuration changes as cases to skip. It reserves ADRs for significant choices such as frameworks, databases, API patterns, and security architecture.
Can I change an ADR after it is accepted?
The skill advises against changing accepted ADRs. Instead, write a new ADR that supersedes the old one, and update the status of the old record.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Choose this skill if your software team wants a consistent written record of framework, database, and architecture choices kept in version-controlled docs with pull request review. Skip it for minor upgrades, bug fixes, routine config changes, non-technical decisions, or teams that do not keep their documentation in version control.
Download the skill