adr

An Agent Skill that turns architectural decisions made during a coding session into Architecture Decision Records, written in strict Nygard format.

The agent detects the decision, drafts the ADR, and shows you the exact file content and path. It waits for your confirmation before writing anything.

What it does

• Detects architectural decisions in the conversation: technology choices, patterns, and tradeoffs that constrain future work. Bug fixes, refactors and config tweaks are ignored on purpose.
• Writes one ADR per decision using Nygard's four sections (Status, Context, Decision, Consequences), with nothing else added.
• Names files by intent, so you get use-postgresql-for-primary-storage.md instead of a numeric or date prefix.
• Handles supersession: it matches the ADR being replaced in docs/adr/, marks the new one Accepted, supersedes <file> and updates the old one to Superseded by <file>.
• Handles status-only changes, so "we dropped the Redis cache" flips the existing ADR to Deprecated instead of creating a new record.
• Previews every file it will create or modify before writing.

Installation

Using the skills CLI, which installs into whichever agents it detects (Claude Code, Cursor, Codex, Copilot, OpenCode, and others):

# in the project that should have the skill
npx skills add jairmedeiros/adr

# or globally, for all your projects
npx skills add -g jairmedeiros/adr

Or clone into the skills directory of your agent by hand. The folder has to be named adr, since the spec requires name to match the parent directory:

# personal (all projects)
git clone https://github.com/jairmedeiros/adr ~/.claude/skills/adr

# project-scoped, committed with the repo
git clone https://github.com/jairmedeiros/adr .claude/skills/adr

Other clients use different paths: .agents/skills/ for Cursor, Codex, Copilot and VS Code, ~/.config/opencode/skills/ for OpenCode. See the client showcase for the full list.

Usage

The skill activates on its own when a session contains a decision worth recording:

"We're going with PostgreSQL instead of SQLite. Document that decision."

"Record why we chose event sourcing for the orders service."

"We're moving off JWT to server-side sessions. Capture the tradeoff."

Or invoke it explicitly at the end of a design discussion:

/adr

If nothing architectural happened, it says No architectural decisions detected in this session. and stops.

Output

ADRs land in docs/adr/ (created if missing). A generated record looks like this:

# Use PostgreSQL for Primary Storage

## Status

Accepted

## Context

The application requires multi-user concurrent access. SQLite was considered
for simplicity but its file-level locking makes it unsuitable for concurrent
writes from multiple users.

## Decision

Use PostgreSQL as the primary relational database. All persistent application
data will be stored in PostgreSQL.

## Consequences

Multi-user concurrent access is supported reliably. Local development requires
a running PostgreSQL instance, which adds setup overhead compared to SQLite.

That goes to docs/adr/use-postgresql-for-primary-storage.md once you answer y to the preview. Walkthroughs of the supersession and status-change flows are in references/examples.md.

Conventions it enforces

Aspect	Rule
Title	Present-tense imperative verb phrase: "Use X", "Choose Y"
Status	One of Accepted, Rejected, Deprecated, Superseded, inferred from the session
Sections	Exactly four; anything like "Alternatives Considered" or "References" is left out
Filename	[verb]-[description].md, lowercase, dash-separated, no number or date prefix
Location	docs/adr/
Granularity	One ADR per decision; multiple decisions are never merged

The skill never writes without confirmation, and it never commits to git. Staging and committing stay in your hands.

Repository structure

adr/
├── SKILL.md              # frontmatter + agent instructions
├── references/
│   └── examples.md       # worked examples, loaded on demand
├── LICENSE
└── README.md

SKILL.md holds the core workflow. references/examples.md is pulled into context only when the agent needs a formatting precedent, which follows the progressive disclosure model.

Compatibility

Works with any agent that implements the Agent Skills format. The skill is instructions and templates only, with no scripts, dependencies or network access, so you can read the whole thing before installing it.

Development

Validate the skill against the specification with skills-ref:

skills-ref validate .

References

• Agent Skills specification
• Best practices for skill creators
• Vercel: creating, installing and sharing skills
• Michael Nygard, Documenting Architecture Decisions

License

MIT © Jair Medeiros. See LICENSE.