Architecture Decision Records

Apply Michael Nygard's Architecture Decision Records (ADRs) — lightweight, immutable Markdown documents that capture significant architectural decisions, their context, and their consequences. Covers Nygard's classic format, MADR, when a decision is "architecturally significant", supersession workflow, where to store ADRs, and how to use them as living institutional memory. Use when making a significant technical decision, when joining a project and wondering "why was it built this way", when a past decision starts to bite, or when a team's tribal knowledge is bleeding away through personnel t

5 stars 2 forksSoftware Development Plugin marketplace

Install

Claude Code plugin
/plugin marketplace add vnovakovits/claude-skills

The repo is a Claude Code plugin marketplace. Run /plugin afterwards to pick the plugin that includes this skill.

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add vnovakovits/claude-skills --skill architecture-decision-records
Manual install
git clone --depth 1 https://github.com/vnovakovits/claude-skills.git /tmp/claude-skills
mkdir -p ~/.claude/skills
cp -r /tmp/claude-skills/plugins/engineering-practices/skills/architecture-decision-records ~/.claude/skills/architecture-decision-records

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# Architecture Decision Records (Michael Nygard)

Apply this skill when making a significant architectural or technical decision that future readers — colleagues, your future self, new joiners — will need to understand. ADRs answer the question that's always asked six months later: *"Why did we do it this way?"*

## Core Philosophy

**The why is the hardest thing to recover.** Code captures *what* the system does. Documentation captures *how* to use it. Neither captures *why* a particular path was chosen over alternatives. ADRs fill that gap.

**Decisions, not aspirations.** An ADR records a decision *that was made*, in the moment, with the context available *at that time*. It is a historical record, not a wish list.

**Lightweight.** A few paragraphs of Markdown, in the repository, alongside the code. Not Confluence, not a wiki, not a 40-page document. The cost of writing one must be low or they won't get written.

**Immutable.** Once accepted, an ADR is not edited. If circumstances change, write a new ADR that supersedes the old. The record of changing decisions over time is itself valuable.

**Decentralized institutional memory.** Teams turn over. Companies change. Six months from now, an ADR is the only thing that will tell someone *why* this database was chosen, this pattern adopted, this technology rejected. Without it, the only path to recovering the reasoning is asking the people who made the decision — and they may be gone, or have forgotten.

---
Read the full skill on GitHub

Details

Skill name
architecture-decision-records
Path
plugins/engineering-practices/skills/architecture-decision-records/SKILL.md
License
MIT
Repo updated
16 November 2026

FAQ

What does the Architecture Decision Records skill do?

Apply Michael Nygard's Architecture Decision Records (ADRs) — lightweight, immutable Markdown documents that capture significant architectural decisions, their context, and their consequences. Covers Nygard's classic format, MADR, when a decision is "architecturally significant", supersession workflow, where to store ADRs, and how to use them as living institutional memory. Use when making a significant technical decision, when joining a project and wondering "why was it built this way", when a past decision starts to bite, or when a team's tribal knowledge is bleeding away through personnel t

How do I install the Architecture Decision Records skill?

Claude Code plugin: /plugin marketplace add vnovakovits/claude-skills. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Architecture Decision Records popular?

It lives in vnovakovits/claude-skills, which has 5 GitHub stars and 2 forks.

Related skills

Accidental Cio

5

vnovakovits/claude-skills

Apply Scott Millett's "The Accidental CIO — A Lean and Agile Playbook for IT Leaders" (Wiley, 2024) when designing or reviewing how a technology organisation decides, funds, governs and delivers work. Covers the five components of an adaptive IT operating model (organised, work, govern, talent, lead) and its four themes (outcomes over output, intrinsic motivation, being not doing agile, manage flow not people); matching method and governance to context via Cynefin and Wardley evolution; governance as demand management + funding + measurement + decision rights, shifting from project funding to

Frontend & Design

Agent Retro

5

vnovakovits/claude-skills

Run a retrospective on a coding-agent session and improve the agent's environment, not the code. Combines Derby & Larsen's five-stage retrospective, Shigeo Shingo's poka-yoke (turn a mechanical mistake into a check that makes it impossible), and Matt Pocock's retro categories — navigation, automated checks, coding standards, steering files, tool economy, information access. Covers mining the session transcript for corrections, wrong turns and slow searches; deciding where each fix belongs (analyzer, hook, CI, reviewer standards, CLAUDE.md pointer, skill, doc or memory); the no-op test for stee

AI, LLMs & Agents

API Design

5

vnovakovits/claude-skills

Design APIs that are clear, evolvable, and idiomatic to their protocol — covering REST (Fielding, Richardson Maturity Model, Massé), GraphQL, gRPC/protobuf, versioning strategies, pagination, error responses (RFC 7807 Problem Details), idempotency, authentication, documentation (OpenAPI), and the pragmatic trade-offs between RESTful purity and developer ergonomics. Use when designing a new endpoint, choosing between REST/GraphQL/gRPC, defining versioning, structuring error responses, deciding pagination strategy, or evaluating an existing API's evolvability.

Software Development

Beam Master

8

Freddy-CHEN-ux/00_claude_skills

Shared resource library for Beam AI integration skills. DO NOT load directly - provides common references (setup, API docs, error handling, authentication) and scripts used by beam-connect and individual Beam skills.

Software Development

Behavior Driven Development

5

vnovakovits/claude-skills

Apply Behavior-Driven Development (BDD) by Dan North, Gojko Adzic, Matt Wynne & Aslak Hellesøy, and Liz Keogh — covering the three practices (discovery, formulation, automation), three amigos workshops, Gherkin scenarios, Specification by Example, living documentation, Feature Injection, and pairing BDD with outside-in TDD. Use when starting a new feature, capturing requirements collaboratively, writing acceptance criteria, deciding what scenarios to automate, or fixing a "Cucumber suite" that has become a brittle UI-testing pile.

Software Development

Airtable Master

8

Freddy-CHEN-ux/00_claude_skills

Shared resource library for Airtable integration skills. DO NOT load directly - provides common references (setup, API docs, error handling, field types) and scripts used by airtable-connect, airtable-query, and airtable-sync.

Software Development

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.