Adr

What it does

When your agent uses it

• The user asks to record a decision
• Capture why something was built a certain way

Example prompts

• “Want me to capture this as an ADR?”
• “/adr”

Workflow steps

9 steps, taken from the step headings in SKILL.md.

1. 1Resolve the project root and ADR directory
2. 2Check for existing ADR format
3. 3Confirm the title and framing before drafting
4. 4Determine the next ADR number
5. 5Derive the filename
6. 6Write the ADR
7. 7Present the draft for approval
8. 8Write the file
9. 9Report back

What it can do on your machine

Read from SKILL.md and the folder at commit 48208f5. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  No scripts in the folder and no shell commands in SKILL.md (its code samples are bash and markdown).

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Adr loads about 962 tokens when it runs. Until then it costs about 134 tokens; SKILL.md has 367 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~134

When it runs · the whole SKILL.md, loaded when a task matches

~962

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from jackfranklin/dotfiles at commit 48208f5, republished under its MIT licence (© jackfranklin). 367 words, ~962 tokens.

name

adr

description

Capture an Architecture Decision Record (ADR) for a significant decision made in the current project. Store in the project's adrs/ folder. Use when the user asks to record a decision, log an ADR, or capture why something was built a certain way. PROACTIVELY suggest capturing an ADR whenever a non-obvious architectural choice is made — technology selection, structural trade-offs, rejected alternatives — especially after a discussion where context and reasoning were developed. A good prompt — "Want me to capture this as an ADR?"

disable-model-invocation

true

ls -d adrs/ docs/adr/ docs/decisions/ architecture/decisions/ 2>/dev/null | head -1

mkdir -p adrs

ls adrs/[0-9]*.md 2>/dev/null | sort | tail -1

adrs/<NNNN>-<kebab-title>.md

# <NNNN>. <Title>

Date: <YYYY-MM-DD>
Status: <Accepted | Proposed | Deprecated | Superseded by [NNNN](<link>)>

## Context

What situation, constraint, or requirement forced this decision? What was the problem space?

## Decision

What was chosen and why? State it directly.

## Alternatives Considered

What else was evaluated and why was it not chosen? This is the most important section for future readers — capture each rejected option and the specific reason it lost.

## Consequences

What gets easier? What gets harder? What is accepted as a trade-off?

© jackfranklin, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in claude/skills/adr of jackfranklin/dotfiles.

Open the folder on GitHubat commit 48208f5