Create ADR
Produce one ADR per invocation. An ADR records a decision that has already
been made; if the decision is still open, use /create-rfc. Follow the
five-step process — do not skip Step 2 (validate mandatory fields) or draft
before every mandatory field is present.
Hard rules
- Never invent facts. If a mandatory field is missing, ask. Never fill
Context, Decision, or Consequences with plausible-sounding filler.
- Never edit an existing ADR to change the decision. Supersede with a new
ADR and link back. ADRs are historical records.
- Never skip trade-offs. Consequences must be honest — include what
becomes harder, not just what becomes easier.
- Never write in a language other than the user's. Match the language
the user is using in this session.
Dispatch
Run the process in order. Read the matching reference file fully before
acting — it is the playbook for that step.
| Step |
Read |
Purpose |
| 1 — Gather context |
references/process.md |
Ask for decision, format, status, supersedes |
| 2 — Validate mandatory fields |
references/process.md |
Ensure title, date, status, context, decision, consequences are present |
| 3 — Pick format |
references/formats.md |
MADR (default) / Nygard / Y-Statement |
| 4 — Assign number |
references/numbering.md |
Scan directory, assign next sequential number |
| 5 — Generate + place |
references/process.md + one of templates/adr-{madr,nygard,y-statement}.md |
Fill template, run quality checklist, confirm file location |
Run the quality checklist (references/quality.md) before finalizing —
titles, honest trade-offs, options actually compared, naming convention.
Templates
Pure markdown scaffolds; load only the one for the chosen format:
| Format |
Template |
| MADR (default) |
templates/adr-madr.md |
| Nygard |
templates/adr-nygard.md |
| Y-Statement |
templates/adr-y-statement.md |
Universal rules
- Honesty. Record trade-offs, unknowns, and open questions honestly.
Never cover a gap with an invented answer. If a field cannot be filled,
ask or leave an italicized placeholder (
*to be confirmed*).
- Immutability. ADRs are historical records. Never edit the decision
after the fact — supersede with a new ADR and link
Superseded by ADR-{NNN} on the old one.
- Short is better. 200–500 words is ideal. If longer, move detail to a
linked design doc or RFC.
- Date everything. What seems obvious now will not be in three years.
- Language adaptation. Always write the ADR in the user's language.
- Confirm before writing. Suggest the file path in Step 5; write only
after the user confirms placement.
Sibling skills
Reach for these at any point in the flow:
/create-rfc — the decision has not been made yet. Use RFC to
propose options, gather feedback, and drive alignment. Once the decision
is made, come back to /create-adr to record it./forge — spec-driven implementation. Use /forge specify | design | plan | execute when the ADR is decided and you need to build the thing.
An ADR often lands as a link in a forge design.md.
Attribution
Based on create-adr
by Tech Leads Club, licensed under
CC-BY-4.0. Changes have been
made to the original.
1---2name: create-adr3description: Creates Architecture Decision Records (ADRs) — concise, durable documents that capture the context, decision, and consequences of significant architectural choices so future team members understand *why* things are the way they are. TRIGGER when: the user asks to create or write an ADR, document a decision, record why something was chosen, capture an architectural decision, or preserve the reasoning behind a finalized technical choice. SKIP for: decisions that have not been made yet (use `/create-rfc`), implementation planning or breaking work into tasks (use `/forge plan`), or general documentation that is not a decision record.4---56# Create ADR78Produce one ADR per invocation. An ADR records a decision that has already9been made; if the decision is still open, use `/create-rfc`. Follow the10five-step process — do not skip Step 2 (validate mandatory fields) or draft11before every mandatory field is present.1213## Hard rules1415- **Never invent facts.** If a mandatory field is missing, ask. Never fill16 Context, Decision, or Consequences with plausible-sounding filler.17- **Never edit an existing ADR to change the decision.** Supersede with a new18 ADR and link back. ADRs are historical records.19- **Never skip trade-offs.** Consequences must be honest — include what20 becomes harder, not just what becomes easier.21- **Never write in a language other than the user's.** Match the language22 the user is using in this session.2324## Dispatch2526Run the process in order. **Read the matching reference file fully before27acting** — it is the playbook for that step.2829| Step | Read | Purpose |30|------|------|---------|31| 1 — Gather context | `references/process.md` | Ask for decision, format, status, supersedes |32| 2 — Validate mandatory fields | `references/process.md` | Ensure title, date, status, context, decision, consequences are present |33| 3 — Pick format | `references/formats.md` | MADR (default) / Nygard / Y-Statement |34| 4 — Assign number | `references/numbering.md` | Scan directory, assign next sequential number |35| 5 — Generate + place | `references/process.md` + one of `templates/adr-{madr,nygard,y-statement}.md` | Fill template, run quality checklist, confirm file location |3637Run the quality checklist (`references/quality.md`) before finalizing —38titles, honest trade-offs, options actually compared, naming convention.3940## Templates4142Pure markdown scaffolds; load only the one for the chosen format:4344| Format | Template |45|--------|----------|46| MADR (default) | `templates/adr-madr.md` |47| Nygard | `templates/adr-nygard.md` |48| Y-Statement | `templates/adr-y-statement.md` |4950## Universal rules51521. **Honesty.** Record trade-offs, unknowns, and open questions honestly.53 Never cover a gap with an invented answer. If a field cannot be filled,54 ask or leave an italicized placeholder (`*to be confirmed*`).552. **Immutability.** ADRs are historical records. Never edit the decision56 after the fact — supersede with a new ADR and link `Superseded by57 ADR-{NNN}` on the old one.583. **Short is better.** 200–500 words is ideal. If longer, move detail to a59 linked design doc or RFC.604. **Date everything.** What seems obvious now will not be in three years.615. **Language adaptation.** Always write the ADR in the user's language.626. **Confirm before writing.** Suggest the file path in Step 5; write only63 after the user confirms placement.6465## Sibling skills6667Reach for these at any point in the flow:6869- **`/create-rfc`** — the decision has *not* been made yet. Use RFC to70 propose options, gather feedback, and drive alignment. Once the decision71 is made, come back to `/create-adr` to record it.72- **`/forge`** — spec-driven implementation. Use `/forge specify | design |73 plan | execute` when the ADR is decided and you need to build the thing.74 An ADR often lands as a link in a forge `design.md`.7576## Attribution7778Based on [create-adr](https://github.com/tech-leads-club/agent-skills/blob/main/packages/skills-catalog/skills/(creation)/create-adr/SKILL.md)79by [Tech Leads Club](https://github.com/tech-leads-club), licensed under80[CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/). Changes have been81made to the original.
emiliosheinz