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
Install
/plugin marketplace add vnovakovits/claude-skillsThe repo is a Claude Code plugin marketplace. Run /plugin afterwards to pick the plugin that includes this skill.
npx skills add vnovakovits/claude-skills --skill architecture-decision-recordsgit 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-recordsPersonal 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. ---
Details
- Skill name
architecture-decision-records- Repository
- vnovakovits/claude-skills
- 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
5vnovakovits/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
Agent Retro
5vnovakovits/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
API Design
5vnovakovits/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.
Beam Master
8Freddy-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.
Behavior Driven Development
5vnovakovits/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.
Airtable Master
8Freddy-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.
Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.