adr-author
Skill11 starsChanged 3 months agoMITView on GitHub
Write or amend an architecture decision record (ADR) that a team will want to read and that names exactly what it decides: the modules, functions, paths or settings, and what must or must never happen. Asks whether the decision deserves a record, interviews briefly, follows the repo's existing ADR format and numbering, shows the draft before writing, and self-checks it (hedged decisions, names missing from the code, status and supersede links). Also amends or supersedes a record when the code turned out to be right. Use for "write an ADR", "record this decision", "document the architecture decision we made", "turn this into a decision record", "supersede ADR 4", "our ADR no longer matches the code", or a one-off exception to an existing ADR. Does not judge code against records, and does not make the decision. General prose and docs are clear-and-human.
- Commits and pushes
7 other projects use a version of this.
Adopted by
Most recently taken up by
- rajanrx/skillstheir own version, first seen Nov 8, 2026
- jaskirat1616/grok-skillstheir own version, first seen Nov 1, 2026
- JayRHa/agent-skillstheir own version, first seen Oct 15, 2026
- microsoft/hve-coretheir own version, first seen Oct 13, 2026
- Bioconductor/ai-agent-skillstheir own version, first seen Aug 18, 2026
- Atypical-Consulting/AdrMcptheir own version, first seen Jul 8, 2026
Used with
Projects with it also use 0-template, github-actions-builder and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
JayRHaSkill0-template
Template for creating a new Agent Skill. Copy this folder, rename it to your skill's kebab-case name, and fill in every section. Use this as the starting point whenever you author a new skill for the AgentSkills library.
Also in 3 projects that use this
JayRHaSkillgithub-actions-builder
Builds reliable, fast, and secure GitHub Actions CI/CD workflows with dependency caching, build matrices, scoped secrets, concurrency control, and reusable/composite workflows. Use this skill when the user asks to "create a GitHub Actions workflow", "set up CI", "add CI/CD", "fix a flaky/slow GitHub Actions pipeline", "add a build matrix", "cache dependencies in CI", "write a reusable workflow", "configure deployment with environments and secrets", or mentions files under .github/workflows.
Also in 3 projects that use this
xmqywxSkillmeeting-summarizer
Transform meeting transcripts into structured summaries with action items, decisions, follow-ups, and efficiency analysis. Works with any meeting format.
Also in 3 projects that use this
MehdibargachSkillokr-writer
Turn business goals into structured OKRs with measurable Key Results, linked initiatives, alignment check, and anti-goals. Takes a strategic priority and outputs ready-to-use OKRs.
Also in 3 projects that use this
pbc-osSkillsecrets-manager
Set up and configure cloud secrets management for your AI agent. Guides users through platform selection (GCP, AWS, Azure, 1Password, Doppler, HashiCorp Vault), account setup, CLI configuration, and secure credential storage.
Also in 3 projects that use this
- +7 more from JayRHa
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 7
- microsoft/hve-core★ 1.6ksame name
- jaskirat1616/grok-skills★ 22same name
- JayRHa/agent-skills★ 12same name
- JayRHa/AgentSkills★ 12same name
- Bioconductor/ai-agent-skills★ 10same name
- rajanrx/skills★ 2same name
- Atypical-Consulting/AdrMcp★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository34 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- beadsSkill
- azadvertizerSkill
- business-planSkill
- c7searchSkill
- clear-and-humanSkill
- convert-to-webpSkill
- cv-and-humanSkill
- cv-cover-letterSkill
- cv-evidence-baseSkill
- dev-fleetSkill
- excalidraw-diagramSkill
- frontier-roundsSkill
- ghost-publishSkill
- hook-and-humanSkill
- interview-panelSkill
- job-feedsSkill
- markdown-converterSkill
- nano-banana-pro-jsonSkill
- python-drillSkill
- readabilitySkill
- report-builderSkill
- social-image-prepSkill
- source-snapshotSkill
- spec-readySkill
- spec-to-ticketsSkill
- terraform-registrySkill
- terragrunt-skillSkill
- transcribe-summarizeSkill
- travel-planningSkill
- trilium-captureSkill
- use-linearisSkill
- ux-auditSkill
The file
We split this skill into the rules it gives an agent
10 rules. 0 are common, 7 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 6 edited versions we read keep these.
7
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 21
Is there a decision?: If the user is still choosing ("Kafka or SQS?"), say there is nothing to record yet and stop.
- Distinctive: line 23
Does it deserve a record?: All three must hold (Matt Pocock's ADR criteria):
- Distinctive: line 27
If one fails, say which and stop: write no draft, unless the author still wants it written.
- Distinctive: line 28
Was it questioned?: If the decision was made in this conversation and nobody pushed on it, ask "record as-is?" first.
- Distinctive: line 30
Short interview: Ask only for what is missing: the context and forces, the decision, what it rules out, the consequences, the alternatives …
- Very specific: line 55
Read the ADR directory (look for docs/adr, docs/decisions, doc/adr, adr, architecture/adr, or an existing .adr-dir file).
- Very specific: line 79
Never invent rationale, constraints, consequences or alternatives.
- Distinctive: line 84
Write the file only after the author approves.
- Distinctive: line 96
Run the self-check on the written file.
- Very specific: line 133
Ask the one question that decides the shape: is the old decision wrong now, narrower than written, or right with a one-off exception?
“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
adr-author
Writes the record of a decision a team has already made, precisely enough that a reviewer, a newcomer or a tool can tell later whether the code still follows it. Amends the record when the code turns out to be right.
The rule above all others: a record is for people first. Precision here is a discipline, not a format. Make a sentence more precise only by naming what it already meant. Never rephrase it into a different shape, never drop a qualifier, condition or trade-off, and keep the reasons in Context where a person reads them.
Before writing anything
- Is there a decision? If the user is still choosing ("Kafka or SQS?"), say there is nothing to record yet and stop. Offer frontier-rounds or design-council to make the decision.
- Does it deserve a record? All three must hold (Matt Pocock's ADR criteria):
- hard to reverse: changing your mind later costs something real;
- surprising without context: a future reader would ask "why on earth did they do this?";
- a real trade-off: there were genuine alternatives. If one fails, say which and stop: write no draft, unless the author still wants it written.
- Was it questioned? If the decision was made in this conversation and nobody pushed on it, ask "record as-is?" first. Skip this when the author states a decision they had already made.
- Short interview. Ask only for what is missing: the context and forces, the decision, what it rules out, the consequences, the alternatives worth remembering. One batch of questions at a time; never re-ask what the author already said.
- Keep the author's words. Make one scratch directory for this record, outside the
repository, and print its path:
D="$(mktemp -d "${TMPDIR:-/tmp}/adr-author.XXXXXX")"; echo "$D". Shell state does not survive between commands, so reuse the printed path, never a fixed name another record may have used. Save what the author said about the decision, verbatim, to$D/notes.md. The self-check uses it to prove every figure in the record came from the author.
Every fact needs a source
Context must say what goes wrong without the decision: the harm it prevents. "Newcomers keep writing to the table directly" says what happens, not what it breaks; ask the author what it breaks before writing, and never supply a harm yourself.
A record is evidence for the people who read it later. Every factual claim in it must come from the author's words or from the repository: an incident, a number, a date, a duration, a cost, a count, "we tried X", "this caused Y". Show a short source list with the draft, one line per claim: the claim, then "author" or a file and line in the repository. A claim with no source is asked about, or becomes a visible gap. It is never written in, however plausible it sounds, and never inferred from the code ("the services were coupled" is a claim; the author has to say it).
Follow the repo's convention
Read the ADR directory (look for docs/adr, docs/decisions, doc/adr, adr, architecture/adr,
or an existing .adr-dir file). Match what is there: location, file extension, numbering and
filename pattern, heading set, template family (Nygard, MADR, Y-statement), and how the status,
date and supersede lines are written (plain line, bold label, table row, front matter or a Status
heading). If two schemes are mixed, report the conflict and ask which to follow; do not pick one
silently (Addy Osmani's documentation-and-adrs). Only with no existing records, use the default in
references/writing-guide.md.
Name what the decision is about
For each decision sentence, search the repository for the names it means: a module, a function or
class, a path, a configuration key. Propose them and let the author confirm. Use only confirmed
names (pass only those to --confirmed; the script checks them against your notes of the
author's words), and put each one where the rule is, in Decision or Consequences; a name that appears only in
Context is not part of the decision. A sentence with no confirmed name stays as the author wrote it and goes in the report. A
decision about code that does not exist yet keeps its intended names and says they are planned.
The decision goes in Decision and Consequences; the reasons go in Context; rejected alternatives go
in Considered Options and never bind. references/writing-guide.md has the full guidance, and
references/example-adr.md is one complete record to imitate, with a best-practice checklist.
Draft, show, then write
- Status is Proposed unless the author says the team has accepted it.
- Never invent rationale, constraints, consequences or alternatives. A gap becomes a question, or a
visible placeholder such as
[CONSEQUENCE NEEDED]in the draft (developer-kit adr-drafting). - Show the path, title, status, full draft and source list. Show the full draft as text in your reply, before the command that writes the record, not only inside that command: the author approves what they can read. Never say a draft was shown when it was not. Write the file only after the author approves. If the request already approves the draft ("approve it as you show it"), that counts as approval: show the draft and write it in the same turn. Treat that wording the same way every time.
- Never write a record that still has a placeholder unless the author says to. Ask the open questions first; if the author says "leave it", drop the sentence rather than ship the gap.
- Save the approved draft to
$D/approved-draft.mdbefore you write the record. The comparison below is only worth anything if the draft was saved first; the script refuses a draft file that is newer than the record. Never sleep, touch or copy files to get past a check; a check you had to trick has told you something, so report it instead.
Self-check, then a second look
Run the self-check on the written file. It uses no model and no network.
CHECK="$( { for f in "$PWD/.claude/skills/adr-author/scripts/check_record.py" "$HOME/.claude/skills/adr-author/scripts/check_record.py" "$HOME/.agents/skills/adr-author/scripts/check_record.py"; do [ -f "$f" ] && echo "$f"; done; find -L "$HOME/.claude" "$HOME/.agents" "$HOME/.codex" -path '*adr-author/scripts/check_record.py' 2>/dev/null; } | head -1)"
echo "$CHECK"
python3 "$CHECK" docs/adr/0007-billing-reads-ledger-through-api.md --repo . --sources "$D/notes.md"
python3 "$CHECK" docs/adr/0007-billing-reads-ledger-through-api.md --repo . --sources "$D/notes.md" --intended PlannedNameIt needs Python 3.12 or later and nothing else; uv run works too. If find prints nothing, the
skill is installed somewhere else: use that directory's scripts/check_record.py.
It reports, in plain words: figures (numbers, dates, percentages, durations, counts, amounts) that are not in the author's notes; decision sentences that hedge ("should", "prefer") and so decide nothing yet; names that appear nowhere in the repository; a missing status; a number already taken or out of sequence; supersede links that are one-sided; decision language sitting in Context or the options; mixed filename styles. Each finding is a question for the author, never an automatic fix. A hedge may be a deliberate preference; a missing name may be planned code.
Make at most one revision round from the answers. Then compare the final file with the approved draft and show the author the diff for a second approval; the first approval never covers revisions:
python3 "$CHECK" docs/adr/0007-billing-reads-ledger-through-api.md --repo . --against "$D/approved-draft.md" --confirmed ledger/api.py LedgerIt reports anything that vanished, any figure that appeared, any change to a word that sets the
decision's strength (must, never, only, all...), and any name added without confirmation. Never
create the "approved draft" file from the record you just wrote; that compares the record with
itself. When editing a record that is already committed, use --baseline instead (see amend mode).
Amend mode: when the code turned out to be right
The input is a description of the mismatch from anyone: the author, a reviewer, a pull request comment, or a checking tool's report pasted as text. No particular format is needed.
Ask the one question that decides the shape: is the old decision wrong now, narrower than
written, or right with a one-off exception? Then follow references/amend.md:
- wrong now: a superseding record, and the old record's status changed to say which record replaced it, both in the same change;
- narrower: amend Decision or Consequences and keep the history in the repo's style;
- one-off: record the exception the way the team already does; if it has no way, propose a short note in the record and ask.
The same self-check, comparison and two approvals apply.
Finish
Report: the file path; what the record now commits the team to, in plain words; names not yet in
the code; open questions. Never run git add, git commit or git push. List the changed files
and suggest a commit message with no AI attribution.
A record written this way can also be enforced by a checking tool such as adrcheck, if the team wants that.
What this skill does not do
- It does not judge whether code follows a record.
- It does not choose between options; it records a choice already made.
- It does not convert or rewrite a whole ADR set.
- It does not polish general prose (clear-and-human) or check readability (readability).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

