Does it make the decision for me?

No. It records a decision the team has already reached. It is not for making the decision itself or for tracking the work it leads to.

What sections does the record have?

Four: Context, Decision, Options considered and Consequences. Each rejected option gets one line on why it lost, and a consequence describes effort or a closed door, not a benefit.

Where is the file written?

At {output_folder}/{active_initiative}/adr-{slug}/adr-{slug}.md, with the initiative folder dropped when it is unset. The slug is the decision in kebab-case.

Decision record

SkillDocs & knowledge

The decision-record skill writes an architecture decision record for a choice your team has already made. It mines the conversation for the context, the options weighed, the decision and its consequences, asks only for what is missing, and shows a draft before writing the file. It is not for making the decision itself or for tracking the work that follows.

Connect your AI Use it in a pipeline

Then ask your AI: use the Decision record skill

Details

Instructions available. Your AI can read the instructions. Execution depends on the setup they require.

Account requirements not reviewed. Check the skill instructions before use; Ahel provides instructions and does not run this skill.

No other account needed.

Have the decision already made and the conversation where it was discussed available.

What your AI can do with it

Writes an ADR with Context, Decision, Options considered and Consequences
Mines the conversation for the decision, options and reasons
Asks one question at a time for details that are missing
Gives each rejected option one line on why it lost
Shows the draft and waits for approval before writing the file
Writes the record to the configured output folder and reports the path

Getting started

Have the decision already made and the conversation where it was discussed available.
Make sure BMad is set up in the project, since the skill resolves its config through the BMad scripts.
If BMad is not set up, install the bmad skill and run its setup first.
Invoke the skill and answer its questions about anything missing from the conversation.
Review the draft, approve it, and note the path where the record was written.

What this skill tells your AI

The instructions your AI receives, as published by bmad-code-org/bmad-method in skills/bmad-toolsmith/shapes/plain-skill/assets/sample-skill/SKILL.md and read by Ahel’s review.

You turn a decision the team has reached into a record a newcomer can read a year later and understand why the system is the way it is. That reader was not in the room, so the record names the forces, not just the outcome.

On activation

Config: uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core.output_folder --key core.active_initiative. Script not found: BMad is not set up here; offer the bmad skill's setup, installing bmad first if needed (npx skills add bmad-code-org/BMAD-METHOD --skill bmad), then run it again.
The record lands at {output_folder}/{active_initiative}/adr-{slug}/adr-{slug}.md, dropping /{active_initiative} when unset. {slug} is the decision in kebab-case.

Writing the record

Mine the conversation first: the decision, the options and the reasons are usually already there. Ask only for what is missing, one question at a time: what was decided, what else was considered and why it lost, what this makes harder later.

Write four sections: Context, Decision, Options considered, Consequences. Each option gets one line on why it lost. A consequence is something that will cost effort or close a door, not a benefit restated.

Show the draft and wait. On approval, write the file and tell the user the path.

Signals

GitHub stars: 54k
Forks: 6k
Last commit: Oct 2026

Questions

Does it make the decision for me?: No. It records a decision the team has already reached. It is not for making the decision itself or for tracking the work it leads to.
What sections does the record have?: Four: Context, Decision, Options considered and Consequences. Each rejected option gets one line on why it lost, and a consequence describes effort or a closed door, not a benefit.
Where is the file written?: At {output_folder}/{active_initiative}/adr-{slug}/adr-{slug}.md, with the initiative folder dropped when it is unset. The slug is the decision in kebab-case.

Advanced

Item type: skill
Key: decision-record-bmad-code-org
Source: github.com/bmad-code-org/bmad-method

github.com/bmad-code-org/bmad-method