When to use this
- Right after a non-trivial architectural decision is made (choice of database, service boundary, major library adoption).
- When onboarding needs to understand why a past decision was made and no record exists.
- Not for routine implementation choices with no real trade-off or long-term consequence -- ADRs are for decisions worth defending later.
The skill file
Copy this verbatim. It's written in the SKILL.md format (YAML frontmatter + markdown instructions) that Claude Code, and increasingly other agent tools, read directly.
---
name: adr-writer
description: Write an Architecture Decision Record capturing the context, options considered, trade-offs, and rationale for a significant architectural decision. Use right after a decision is made, or to reconstruct one from available evidence when documenting after the fact.
---
# Architecture Decision Record Writer
An ADR's job is to let someone in a year understand *why*, not just *what*.
Capture the reasoning, not just the outcome.
## Structure
1. **Title**: short, specific ("Use PostgreSQL for the primary datastore,"
not "Database decision").
2. **Status**: proposed / accepted / superseded (with a link to what
superseded it, if applicable).
3. **Context**: the problem/constraint that forced a decision -- what was
actually true at the time (scale, team size, existing stack) that
shaped the options.
4. **Options considered**: each real option that was evaluated, with its
genuine trade-offs -- not a strawman list where one option is obviously
correct and the others are token alternatives.
5. **Decision**: what was chosen, stated plainly.
6. **Consequences**: what this decision makes easier, what it makes
harder or forecloses, and any follow-up work it implies.
## Reconstructing one after the fact
If writing this after the decision was already made without a record:
gather context from commit history, PR discussions, and the people
involved rather than inventing plausible-sounding reasoning. Mark clearly
which parts are reconstructed vs. confirmed.
## Output
One ADR file following this project's existing ADR numbering/location
convention if one exists (commonly `docs/adr/NNNN-title.md`).
Installing it elsewhere
The frontmatter/body split above is Claude Code's convention. Here's how to carry the same instructions into other tools:
Save the file below verbatim (frontmatter included) at that path, project-local or in ~/.claude/skills/ for a user-level skill. Claude Code loads the name/description pair to decide when to pull it in, or you invoke it directly as /adr-writer.
Convert the YAML frontmatter to Cursor's rule format (description, globs, alwaysApply: false) and keep the markdown body as the rule content. Cursor surfaces it by description match, same idea as Claude Code's auto-load.
Codex CLI (and increasingly other agentic CLIs) read AGENTS.md at the repo root as always-on instructions. Paste the markdown body under a heading like ## {title}; for GitHub Copilot's coding agent, the equivalent file is .github/copilot-instructions.md.
Append the markdown body to .windsurfrules at the repo root. Windsurf treats the whole file as always-on context, so keep only the instructions you want applied on every request.
- Writing a list of options where all but the chosen one are obviously strawmen -- defeats the purpose of recording the trade-off.
- Skipping the Consequences section, which is often the most useful part for future readers deciding whether to revisit the decision.
- Inventing reasoning when reconstructing an ADR after the fact instead of marking uncertainty honestly.