How do I install the Adr New skill?

Run npx skillmds@latest add jokerman89/adr-new in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Adr New safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Adr New?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Adr New free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Adr New?

jokerman89 (@jokerman89) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Adr New by jokerman89 — Agent Skill

Name: Adr New
Author: jokerman89

Adr New

Use when a non-trivial decision needs recording to bootstrap a new Architecture Decision Record from the template, asking context-gathering questions to fill Status, Context, Decision, and Consequences. Reach for it whenever you've made or are about to make an architectural choice worth a durable record.

jokerman89 0e6d848 2.9 KB Updated Sep 17, 2026

File contents

You are the adr-new skill.

When to use

Non-trivial architectural decision being made
Operator wants to record decision rationale durably
Pattern emerges that future contributors should understand
After /office-hours or /plan-eng-review session that produced a decision

When NOT to use

Trivial decisions (file names, single-line config) — comment in code suffices
Decisions that aren't final yet — wait until decision lands
Replays of existing ADRs — update existing, don't create new

Workflow

Locate ADR directory. Check .claude/decisions/ exists. If not, recommend scaffolding init first.
Find next ADR number. Scan existing .claude/decisions/NNNN-*.md files. Next = max + 1.
Read template. .claude/decisions/TEMPLATE.md exists? If yes, load. If no, fall back to standard ADR format.
Gather context via AskUserQuestion (sequence):
- Title — one-line decision summary.
- Context — what is the situation that prompts this decision?
- Decision — what we will do.
- Alternatives considered — what else was on the table?
- Consequences — what becomes easier? Harder? What risks?
- Related ADRs — supersedes / informed by?
Generate slug. From title, kebab-case, ≤6 words.
Write ADR file. .claude/decisions/<NNNN>-<slug>.md. Status: Proposed by default.

Commit. Branch + commit:

git checkout -b adr-<NNNN>-<slug>
git add .claude/decisions/<NNNN>-<slug>.md
git commit -m "adr: <NNNN> <title>"

Report. Path + branch + next-step prompt.

Output format

ADR-NEW: <NNNN>-<slug>

Title: <title>
Status: Proposed
File: .claude/decisions/<NNNN>-<slug>.md
Branch: adr-<NNNN>-<slug>

Sections populated:
- ✓ Context
- ✓ Decision
- ✓ Alternatives
- ✓ Consequences
- ✓ Related ADRs

Next:
- [ ] Review draft
- [ ] git push + open PR
- [ ] Update status to "Accepted" when merged

Edge cases

No .claude/decisions/ directory — recommend bin/li-scaffold init first.
Decision already documented in lessons.md — recommend cross-reference.
Decision spans multiple repos — recommend ADR-as-RFC in shared design-docs repo.
TEMPLATE.md custom — respect repo customization; load whatever's there.

ADR is part of session-harness

ADRs travel with the repo. Future Claude sessions read them at session-start (per CLAUDE.md). They're how decisions persist across sessions, across operators, and across years.

This skill is the bootstrap. Maintaining ADRs is operator-discipline.

---name: adr-newdescription: Use when a non-trivial decision needs recording to bootstrap a new Architecture Decision Record from the template, asking context-gathering questions to fill Status, Context, Decision, and Consequences. Reach for it whenever you've made or are about to make an architectural choice worth a durable record.---You are the adr-new skill.## When to use- Non-trivial architectural decision being made- Operator wants to record decision rationale durably- Pattern emerges that future contributors should understand- After /office-hours or /plan-eng-review session that produced a decision## When NOT to use- Trivial decisions (file names, single-line config) — comment in code suffices- Decisions that aren't final yet — wait until decision lands- Replays of existing ADRs — update existing, don't create new## Workflow1. **Locate ADR directory.** Check `.claude/decisions/` exists. If not, recommend scaffolding init first.2. **Find next ADR number.** Scan existing `.claude/decisions/NNNN-*.md` files. Next = max + 1.3. **Read template.** `.claude/decisions/TEMPLATE.md` exists? If yes, load. If no, fall back to standard ADR format.4. **Gather context via AskUserQuestion (sequence):** - **Title** — one-line decision summary. - **Context** — what is the situation that prompts this decision? - **Decision** — what we will do. - **Alternatives considered** — what else was on the table? - **Consequences** — what becomes easier? Harder? What risks? - **Related ADRs** — supersedes / informed by?5. **Generate slug.** From title, kebab-case, ≤6 words.6. **Write ADR file.** `.claude/decisions/<NNNN>-<slug>.md`. Status: Proposed by default.7. **Commit.** Branch + commit: ```bash git checkout -b adr-<NNNN>-<slug> git add .claude/decisions/<NNNN>-<slug>.md git commit -m "adr: <NNNN> <title>" ```8. **Report.** Path + branch + next-step prompt.## Output format```ADR-NEW: <NNNN>-<slug>Title: <title>Status: ProposedFile: .claude/decisions/<NNNN>-<slug>.mdBranch: adr-<NNNN>-<slug>Sections populated:- ✓ Context- ✓ Decision- ✓ Alternatives- ✓ Consequences- ✓ Related ADRsNext:- [ ] Review draft- [ ] git push + open PR- [ ] Update status to "Accepted" when merged```## Edge cases- **No `.claude/decisions/` directory** — recommend `bin/li-scaffold init` first.- **Decision already documented in lessons.md** — recommend cross-reference.- **Decision spans multiple repos** — recommend ADR-as-RFC in shared design-docs repo.- **TEMPLATE.md custom** — respect repo customization; load whatever's there.## ADR is part of session-harnessADRs travel with the repo. Future Claude sessions read them at session-start (per CLAUDE.md). They're how decisions persist across sessions, across operators, and across years.This skill is the bootstrap. Maintaining ADRs is operator-discipline.

Frequently asked questions