recording-decisions skill (riekelt) for Claude Code: write ADRs and decision log entries

Makes Claude write down why a choice was made, as a full ADR or a short decision-log entry, and never edit accepted decisions.

Installs: 20.4K; on skills.sh
Stars: 36; on GitHub
Updated: Sep 2026; last repo commit

recording-decisions offers two formats by weight: a full ADR in Nygard format for architecture-level decisions, and a lightweight decision log for the running stream of smaller choices. The negative consequences section is mandatory and each alternative carries its strongest argument. Both are append-only, so a wrong entry gets a new dated entry that supersedes it. It also watches for signals such as we decided X instead of Y and offers to record the decision. It lists technical-writing as required background.

Good for

Teams that decide things in chat or pull-request threads and lose the reasoning
Architects who keep ADRs in the repo
Anyone who wants a lightweight running log of smaller choices

Install recording-decisions

Claude Code

Copy this prompt.

Install the recording-decisions skill in Claude Code. Run this command:

/plugin marketplace add riekelt/technical-writer
/plugin install technical-writer@technical-writer

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route, not both, or you get every skill twice. The skills CLI route must include technical-writing, which recording-decisions lists as REQUIRED BACKGROUND in its SKILL.md.

From the project README. Source.

What's in the skill

When it loads

Use when a decision needs recording - an ADR, a decision log entry, or when someone asks to write down why something was chosen, rejected, or superseded. Encodes the ADR and decision-log formats. Use whenever a choice was made that would otherwise live only in chat, even if nobody says "ADR".

Sections in SKILL.md

Overview
When to invoke, and not
ADR
Context
Decision
Consequences
Alternatives considered
References
Decision log (lightweight)
YYYY-MM-DD
[Decision stated as an imperative sentence]
Rules

Key facts

Author: riekelt (owner of the GitHub repo)
License: MIT (LICENSE file and plugin manifest)
Installs on skills.sh: 20,356 as of 2026-11-02
GitHub stars: 36 for the whole riekelt/technical-writer repo, 2026-11-02
What is inside: 1 file: SKILL.md
Needs: The technical-writing skill (SKILL.md lists it as REQUIRED BACKGROUND)
Part of: The technical-writer plugin: 11 skills, 2 agents and 2 commands
Last repo commit: 2026-09-13
Works in: Claude Code per the README install section. The repo also ships Codex and Cursor plugin manifests.

What it includes

Nygard format, one decision per record
Status, date and deciders in a header table, then Context, Decision, Consequences (positive, negative and neutral), Alternatives considered and References. Negative consequences may not be empty.
Try: “Write an ADR for choosing Postgres over DynamoDB for the orders service.”
Write · ADR
Dated entries with the rule, reasons and the rejected option
Each entry states the decision as an imperative sentence, a one-paragraph rule, the reasons, and what was chosen instead and why not.
Write · Decision log
Triggers on choices that would otherwise live only in chat
Besides explicit requests, it reacts to phrases such as we decided X instead of Y or let's just go with, and offers to record the decision. Record it before citing it.
Read · When to invoke
Append-only, record the why, capture negative results
A wrong entry is superseded, not edited. The only edit to an accepted ADR is its Status line. Relative dates become absolute, and a search that found nothing is a result.
Write · Rules

From the official docs

Permissions

Low risk

Claude writes decision records that your team will treat as history, so check them before they are accepted.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It writes files in your repo
SKILL.md treats an accepted ADR as immutable: the only permitted edit is its Status line, and corrections are new entries. Our advice: check titles and reasons before you commit a record. github.com
The plugin route adds 2 agents and 2 commands
The plugin ships agents prose-reviewer and doc-grounder (both with Read, Glob, Grep and Bash tools) and the commands /prose-review and /ground-docs. The plugin folder has no hooks or MCP config. Use the skills command in the install box if you want only this skill. github.com

Technical details

Turning on read-only	No read-only mode. The skill tells Claude to write or edit documents.
Sign-in and keys	SKILL.md names no account or API key.
Data retention	SKILL.md names no logging or telemetry.
Scopes	Claude writes ADR and decision-log files in your repo

Questions

What does recording-decisions do?

It makes Claude record a decision as an ADR or a decision-log entry, with the context, the choice, the consequences including negative ones, and the alternatives.

How do I install recording-decisions?

Use the install box at the top of this page. The plugin route installs the whole set. The skills command route names technical-writing as well, because this skill lists it as required background.

ADR or decision log: which one?

SKILL.md says a full ADR is for a decision with architecture-level consequences and a log entry is for the running stream of smaller choices.

Can Claude edit an accepted ADR?

The skill says no. The sole permitted edit to an accepted ADR is its Status line gaining Superseded by ADR-XXX. A new context is a new entry.

recording-decisions vs writing-design-docs?

Use writing-design-docs while a decision is still being argued. Once it is accepted, SKILL.md says the Why & What box from the design doc becomes the ADR.

Is recording-decisions safe to install?

The skill folder holds only SKILL.md, so it bundles no scripts. It makes Claude write ADR and decision-log entries as files in your repo. Review the diff, as you would any edit.

Can I use recording-decisions in the Claude app or Cursor?

The README documents Claude Code, and the repo also ships Codex and Cursor plugin manifests. It does not mention the Claude app. Our advice: this page offers no Claude app upload because the skill works on documents inside a repository, so use Claude Code or Codex.

Information

updated Nov 2, 2026

Repository: riekelt/technical-writer
Folder: plugins/technical-writer/skills/recording-decisions

riekelt/technical-writer skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6

README · github.com
marketplace.json · github.com
recording-decisions on skills.sh · skills.sh
SKILL.md · github.com
LICENSE · github.com
writing-design-docs SKILL.md · github.com