01
It starts by itself
decision docs change. Runs in GitHub Actions or pre-commit hook.
- ↻ decision docs change
pull request touches docs/decisions/
skymavis · 7K installsDecision Records skill
Runs by itself, decision docs change.
Keep decision records valid and linked.
Install the Decision Records skill and make it a habit: follow https://gethabit.dev/skills/skymavis/decision-records.md
- 1Copy
- 2Paste into Claude Code, Codex or Cursor
- 3It runs by itself
7K installs1 starsMIT licenceSource on GitHub ↗
Decision Records
by skymavis · 7K installs
The skill
The decision records skill drafts, promotes, archives and supersedes ADR-style records with the bundled decisions.py tool, and keeps INDEX.md and cross-links generated.
Only when you ask.
The habit
Keep decision records valid and linked.
↻ Runs by itselfdecision docs change
How the habit works.
You don't have to.
When does it start? How does it check its work? What does it remember?
One run, step by step.
Then it stops.
Stops after one check and rebuild per run.
- 01
Check
Your agent runs python scripts/decisions.py check.
- 02
Read warnings
It reads WARN lines for ID collisions with origin/main and cites of superseded records.
- 03
Rebuild
It runs decisions.py build --relink to regenerate INDEX.md and links.
- 04
Tidy drafts
It checks drafts against drafts/_template.md and removes padding.
- 05
Ask before promote
It runs promote only after your explicit go-ahead in that turn.
What it may do.
Nothing more.
It writes only in its own folder and asks you before anything goes out.
- Writes only indocs/decisions/**
- Talks tono outside service
- Sendsnothing
- Your OKIt asks you before anything goes out.
Is it for you?
Use it when it fits.
Read both lists. If the left one sounds like you, the Decision Records skill helps.
Use it when
- ✓ You draft a new decision record
- ✓ You supersede an old decision
- ✓ You set up ADRs in a repo
Skip it when
- – You keep decisions in a wiki
- – You need a one-off note
Decision Records skill, answered.
Is there a proposed status?
No. Proposing means opening a PR that promotes a draft.
Can accepted records be rewritten?
No. Changing course needs supersession; only small maintenance edits are allowed.
How do I install the Decision Records skill?
Copy the prompt at the top into your agent. It installs the skill from skymavis/skills and sets up the habit. Or run npx skills add skymavis/skills --skill decision-records.
Is the Decision Records skill free?
Yes. It is published under MIT. Habit is free too.
Decision Records. Now as a habit.
Install the Decision Records skill and make it a habit: follow https://gethabit.dev/skills/skymavis/decision-records.md
All skymavis skills →More docs skills →
Works in
- Claude Code
- Codex
- Cursor
- ChatGPT
- Claude app
Made by skymavis, published under MIT. Habit links to the original and never changes it. Is this your skill?