About create-adr
create-adr is a workflow skill for recording decisions that have already been made as Architecture Decision Records. It guides users through field validation, format and number selection, drafting, and review while preserving ADRs as historical records.
Key features
- 01Validates mandatory ADR fields
- 02Supports MADR, Nygard, and Y-Statement
- 03Assigns sequential document numbers
- 04Checks trade-offs and document quality
- 05Requires confirmation before writing
Use cases
- 01Document a finalized architecture decision
- 02Choose an ADR format for a team record
- 03Supersede an outdated decision with a new ADR
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/create-adrin Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
README.mdreferences/formats.mdnumbering.mdprocess.mdquality.mdtemplates/adr-madr.mdadr-nygard.mdadr-y-statement.mdDetails
From the project READMECreate 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 in order: Step 2 validates the mandatory fields, and
drafting starts once every one of them 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.
- Write in the user's language — the one they are using in this session, every section of the document included.
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.
- 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-adrto record it./forge— spec-driven implementation. Use/forge specify | design | plan | executewhen the ADR is decided and you need to build the thing. An ADR often lands as a link in a forgedesign.md.
Attribution
Based on create-adr by Tech Leads Club, licensed under CC-BY-4.0. Changes have been made to the original.