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 lets your coding agent notice significant technical choices made during a session and propose writing them down as short Architecture Decision Records (ADRs). It is aimed at development teams and solo developers who want a lasting record of why the codebase looks the way it does. After this guide you will know what the skill does, how to install it, how to trigger it with natural requests, and what to check before you approve a record.
Architecture Decision Recordsaffaan-m/ECC · MIT Download the skill Quick start
- 1Download and unzip. Download the skill ZIP from the directory page and unzip it into ~/.claude/skills/ or your project's .claude/skills/ folder.
- 2Or upload in the Claude apps. If you use the Claude apps, go to Settings → Capabilities → Skills and upload the skill there instead.
- 3Make a significant decision. Work with the agent on a real technical choice, such as a framework, database or authentication approach.
- 4Approve the draft. When the agent proposes an ADR, review the context, alternatives and consequences. Approve only if it is accurate.
- 5Check the index. After approval, confirm the new file appears in docs/adr/ and that docs/adr/README.md lists it.
- 6Query past decisions later. Ask why a choice was made and the agent will look up the matching record in the index.
What the skill makes the agent do
When you choose something significant, such as a framework, database, API style or authentication approach, the skill makes the agent recognise the decision and offer to record it. Each record captures the context, the decision, the alternatives considered and why they were rejected, and the consequences.
The records are stored in docs/adr/, along with an index file so future team members can see why the code is shaped as it is. The skill asks for your approval before creating files or writing anything.
- Detects explicit signals such as "let's go with X" or "we should use X instead of Y".
- Detects implicit signals such as comparing two frameworks and reaching a conclusion, or choosing an authentication strategy.
- Proposes a draft ADR for review and writes it only after you explicitly approve.
Install the skill from the ZIP or the Claude apps
Download the ZIP from the directory page and unzip it. For a personal setup, place the unzipped skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.
If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload
Trigger the skill with natural requests
You do not need a special command. Ask in plain language, either to record a decision you have just made or to look up why an earlier one was made.
The skill also activates during planning when trade-offs are being discussed, and when you ask why a technology was chosen, in which case the agent reads the existing records.
- "Let's record this decision as an ADR."
- "Create an ADR for why we chose Postgres over Mongo."
- "Why did we pick REST over GraphQL?" (reads existing ADRs)
- "We chose X over Y because of the trade-off, so let's document it."
Walk through a typical capture
When a decision is detected, the agent works through a fixed sequence: it identifies the core choice, gathers context and constraints, documents the alternatives and why they were rejected, states the consequences, assigns the next number by scanning docs/adr/, shows you a draft, and then updates the index.
On first use, if docs/adr/ does not exist, the agent offers to create the directory, a README.md index with a table header, and a blank template.md for manual use. It will not create these files without your agreement.
- Index format: a markdown table with ADR number, title, status and date columns.
- Record statuses: proposed, accepted, deprecated, or superseded by a later ADR.
- Files are named like docs/adr/NNNN-decision-title.md.
Know what the skill will not record
The skill is deliberately selective. It says trivial choices such as variable naming or formatting do not need a record, because the record would only add noise. Its guidance also asks that records stay short, ideally readable in two minutes, with the context section under about ten lines.
If your project already uses a different decision-log system, this skill would create a parallel set of records, so it is a poor fit there.
- Do not use it for naming or formatting decisions.
- Do not use it to backfill past decisions without noting their original dates.
- When a decision is replaced, the old record should link to its replacement.
What people use it for
- Recording why a team chose a database or frontend framework so newcomers do not re-open the debate.
- Writing down an API style or authentication decision made during a planning session.
- Keeping a solo project's reasons for past choices, which are easy to forget months later.
- Looking up the reasoning behind existing code by asking the agent to read docs/adr/README.md.
Frequently asked questions
Is the architecture decision records skill free?
The skill is published under the MIT licence, as stated on this page. Check the licence file in the source repository for the full terms.
What do I need to install the architecture-decision-records skill?
The skill lists no special requirements. You download the ZIP, unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
Does the skill run scripts or use the network?
No. According to the skill's listing, it runs no scripts and uses no network. It works by writing markdown files in docs/adr/ after you approve them.
Will the skill create ADR files without asking me?
No. It asks for your approval before creating files or writing anything. If you decline, the draft is discarded without writing a file.
How is this different from just writing decisions in a PR comment?
The skill stores each decision as a file in docs/adr/ alongside the code, with an index, instead of leaving it in a chat thread, PR comment or memory. The alternatives and consequences are recorded in a fixed structure.
Should I use it for every small choice?
No. The skill itself says trivial choices such as variable naming or formatting do not need an ADR, because the record would add noise.
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
Use this skill if your team or future self needs a lasting written trail of why significant technical choices were made, especially when decisions currently live in chat or memory. Skip it for trivial choices, or if your project already has a different decision-log system, since it would create a parallel set of records.
Download the skill