How do I install the Adr skill?

Run npx skillmds@latest add jessedegans/adr in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Adr?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

jessedegans (@jessedegans) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Adr by jessedegans — Agent Skill

Name: Adr
Author: jessedegans

Adr

Record Architecture Decision Records (ADRs) when significant technical decisions are made. MUST trigger when switching, migrating, or replacing libraries, SDKs, frameworks, databases, or infrastructure. MUST trigger when making decisions that shape how the system works going forward: deployment strategies, service boundaries, data flow patterns, auth models, API design. Also trigger when choosing between alternatives, making trade-offs, or changing a previous approach. Common signals: "let's go with X", "we should use Y", "I've decided to", "switching from X to Y", "the trade-off is", "pros and cons of", "why did we choose X?", or "document this decision". Even if the user doesn't say "ADR", if a decision is being made that future-them would want to remember the reasoning for, this skill applies. Record the ADR proactively, don't wait to be asked.

jessedegans 844c28a 4.0 KB Updated Sep 17, 2026

File contents

Architecture Decision Records

ADRs capture the why behind significant technical decisions so that future-you (or teammates) can understand the reasoning without re-deriving it.

When to record an ADR

Record one when:

Choosing between real alternatives - at least two viable options existed and you picked one for reasons
The decision is hard to reverse - switching later would cost significant effort
Future-you would ask "why did we do this?" - the reasoning isn't obvious from the code
Changing a previous decision - especially important to capture what changed and why

Don't record ADRs for: trivial choices (variable names, formatting), obvious decisions (use git for version control), or temporary experiments.

On project start

If docs/adr/ exists, skim the titles to understand past decisions. If you're about to recommend something that contradicts an existing ADR, flag it:

"Heads up: ADR 0003 chose X for Y reason. Are we revisiting that decision? If so I'll record a new ADR."

How to record

Step 1: Find or create the ADR directory

Look for existing ADRs in the project. Default location: docs/adr/. Create it if it doesn't exist.

Step 2: Determine the next number

Read existing ADR files to find the highest number, increment. Files follow this pattern:

NNNN-short-slug.md

Zero-padded to 4 digits. Start at 0001 if none exist. Slug should be lowercase, hyphen-separated, 3-6 words describing the decision.

Examples: 0001-use-postgres-over-dynamodb.md, 0002-monorepo-structure.md

Step 3: Write the ADR

# NNNN. Title of Decision

**Date**: YYYY-MM-DD

## Context

What is the situation? What problem are we solving? What constraints exist?
2-4 sentences. Enough background for someone unfamiliar to understand why
a decision was needed.

## Options Considered

- **Option A**: Brief description. Key trade-off.
- **Option B**: Brief description. Key trade-off.

## Decision

What did we decide and why? Be specific about the reasoning.
Reference concrete evidence (benchmarks, cost calculations,
compatibility requirements) when available.

## Consequences

- What becomes easier or possible
- What becomes harder or impossible
- What we'll need to watch out for
- Any follow-up work this creates

Writing rules

Be concrete, not abstract. "Postgres handles our query patterns with 2ms p99 vs DynamoDB's 8ms" beats "the relational DB performed better."
Capture reasoning, not just conclusion. The code shows what; the ADR captures why.
Include numbers when you have them. Costs, latency, accuracy, memory usage.
Keep it short. Half a page, not three pages. Link to detailed docs if needed.

Step 4: Summarize

After writing, tell the user:

The file path
A one-line summary of what was recorded
Note it'll be committed with the next git commit

Proactive suggestions

When you notice a decision being made in conversation but the user hasn't asked for an ADR:

"This looks like a decision worth recording as an ADR. Want me to capture it in docs/adr/?"

One suggestion per decision. If they say no or ignore it, move on. Don't be pushy.

---name: adrdescription: Record Architecture Decision Records (ADRs) when significant technical decisions are made. MUST trigger when switching, migrating, or replacing libraries, SDKs, frameworks, databases, or infrastructure. MUST trigger when making decisions that shape how the system works going forward: deployment strategies, service boundaries, data flow patterns, auth models, API design. Also trigger when choosing between alternatives, making trade-offs, or changing a previous approach. Common signals: "let's go with X", "we should use Y", "I've decided to", "switching from X to Y", "the trade-off is", "pros and cons of", "why did we choose X?", or "document this decision". Even if the user doesn't say "ADR", if a decision is being made that future-them would want to remember the reasoning for, this skill applies. Record the ADR proactively, don't wait to be asked.---# Architecture Decision RecordsADRs capture the *why* behind significant technical decisions so that future-you (or teammates) can understand the reasoning without re-deriving it.## When to record an ADRRecord one when:- **Choosing between real alternatives** - at least two viable options existed and you picked one for reasons- **The decision is hard to reverse** - switching later would cost significant effort- **Future-you would ask "why did we do this?"** - the reasoning isn't obvious from the code- **Changing a previous decision** - especially important to capture what changed and whyDon't record ADRs for: trivial choices (variable names, formatting), obvious decisions (use git for version control), or temporary experiments.## On project startIf `docs/adr/` exists, skim the titles to understand past decisions. If you're about to recommend something that contradicts an existing ADR, flag it:> "Heads up: ADR 0003 chose X for Y reason. Are we revisiting that decision? If so I'll record a new ADR."## How to record### Step 1: Find or create the ADR directoryLook for existing ADRs in the project. Default location: `docs/adr/`. Create it if it doesn't exist.### Step 2: Determine the next numberRead existing ADR files to find the highest number, increment. Files follow this pattern:```NNNN-short-slug.md```Zero-padded to 4 digits. Start at `0001` if none exist. Slug should be lowercase, hyphen-separated, 3-6 words describing the decision.Examples: `0001-use-postgres-over-dynamodb.md`, `0002-monorepo-structure.md`### Step 3: Write the ADR```markdown# NNNN. Title of Decision**Date**: YYYY-MM-DD## ContextWhat is the situation? What problem are we solving? What constraints exist?2-4 sentences. Enough background for someone unfamiliar to understand whya decision was needed.## Options Considered- **Option A**: Brief description. Key trade-off.- **Option B**: Brief description. Key trade-off.## DecisionWhat did we decide and why? Be specific about the reasoning.Reference concrete evidence (benchmarks, cost calculations,compatibility requirements) when available.## Consequences- What becomes easier or possible- What becomes harder or impossible- What we'll need to watch out for- Any follow-up work this creates```### Writing rules- **Be concrete, not abstract.** "Postgres handles our query patterns with 2ms p99 vs DynamoDB's 8ms" beats "the relational DB performed better."- **Capture reasoning, not just conclusion.** The code shows *what*; the ADR captures *why*.- **Include numbers when you have them.** Costs, latency, accuracy, memory usage.- **Keep it short.** Half a page, not three pages. Link to detailed docs if needed.### Step 4: SummarizeAfter writing, tell the user:- The file path- A one-line summary of what was recorded- Note it'll be committed with the next git commit## Proactive suggestionsWhen you notice a decision being made in conversation but the user hasn't asked for an ADR:> "This looks like a decision worth recording as an ADR. Want me to capture it in `docs/adr/`?"One suggestion per decision. If they say no or ignore it, move on. Don't be pushy.

Frequently asked questions

Adr