adr-writer
Skill1 starsChanged 5 days agoMITView on GitHub
Write an Architecture Decision Record capturing a decision the user describes, in Michael Nygard ADR format (Status, Context, Decision, Consequences) with an added Considered Alternatives section. Use when recording a significant architectural or technology choice.
13 other projects use a version of this.
Adopted by
Most recently taken up by
- llopresto87/Cypresstheir own version, first seen Nov 11, 2026
- Mathews-Tom/armorytheir own version, first seen Nov 1, 2026
- pathiec92/claude-skillstheir own version, first seen Oct 25, 2026
- mikulgohil/claude-skillstheir own version, first seen Oct 13, 2026
- GabrielHenriqueCA/cortex-aitheir own version, first seen Oct 11, 2026
- govctl-org/govctltheir own version, first seen Oct 9, 2026
Other versions13 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 13
- Mathews-Tom/armory★ 340same name
- govctl-org/govctl★ 276same name
- llopresto87/Cypress★ 121same name
- applypack/applypack★ 32same name
- 45ck/software-architecture-skills★ 16same name
- Ecoa-PUC-Rio/GAIDE★ 8same name
- jcarlos78/GAIDE★ 8same name
- brpaz/agent-skills★ 1same name
- GabrielHenriqueCA/cortex-ai★ 1same name
- kuju63/skills★ 0same name
3 more not listed
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 repository163 other files it gives its agents.
- agents.mdAGENTS.md
- 3d-asset-handoff-sheetSkill
- accessibility-regression-auditorSkill
- agent-memory-designerSkill
- agent-trajectory-evaluatorSkill
- alerting-rules-tunerSkill
- analysis-memo-writerSkill
- annotation-disagreement-ledgerSkill
- annotation-task-spec-builderSkill
- api-deprecation-plannerSkill
- api-error-contract-designerSkill
- architecture-diagram-generatorSkill
- asset-metadata-review-ledgerSkill
- auth-flow-reviewerSkill
- background-job-reliability-auditorSkill
- branch-rebaserSkill
- brand-voice-profilerSkill
- bundle-analyzerSkill
- cache-policy-designerSkill
- canary-release-plannerSkill
- caption-correction-ledgerSkill
- changelog-from-prsSkill
- chart-chooserSkill
- chunking-strategy-optimizerSkill
- circular-dependency-breakerSkill
- claude-settings-auditorSkill
- code-example-verifierSkill
- cold-email-deliverability-auditorSkill
- cold-start-optimizerSkill
- commit-splitterSkill
- competitor-teardownSkill
- component-spec-writerSkill
- connection-pool-tunerSkill
- content-repurposerSkill
- contract-obligation-registerSkill
- contract-test-designerSkill
- conventional-commitsSkill
- cors-configuratorSkill
- coverage-gap-finderSkill
- crm-export-auditorSkill
- dashboard-designerSkill
- data-retention-auditorSkill
- dataset-first-lookSkill
- dead-code-finderSkill
- deadlock-diagnoserSkill
- decision-log-reconcilerSkill
- dependency-auditSkill
- dependency-upgrade-plannerSkill
- design-brief-writerSkill
- design-critique-checklistSkill
- design-token-extractorSkill
- devcontainer-designerSkill
- distributed-tracing-instrumenterSkill
- dockerfile-optimizerSkill
- email-sequence-drafterSkill
- embedding-index-tunerSkill
- embedding-set-inspectorSkill
- entity-match-candidate-ledgerSkill
- exit-ticket-builderSkill
- extract-moduleSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
4 rules. 0 are common, 1 is distinctive, and 3 are very specific to this project.
0
Common
Most of the 8 edited versions we read keep these.
1
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
- Very specific: line 25
Read package.json / requirements.txt / go.mod / Cargo.toml for the current stack and what's already a dependency.
- Very specific: line 27
Check docker-compose.yml, *.tf, CI config, and any README/CLAUDE.md for deployment targets, scale signals, and stated team conventions.
- Very specific: line 30
Set the status deliberately: Use Proposed for an open decision under review, Accepted once it's agreed, Deprecated for an outdated record, …
- Distinctive: line 90
After writing, report the path and note any section (e.g.
“Common” is measured: kept by at least 6 in 10 of the 8 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
Turn an architectural decision into a durable, reviewable record. The skill takes the decision the user describes, gathers the real constraints that shaped it from the repository, and writes a Nygard-style Architecture Decision Record — context and problem, the decision and its status, the consequences, and the alternatives that were considered and rejected. The result is a numbered, immutable document that explains why a choice was made to whoever reads the code in two years.
When to use this skill
- You made a consequential, hard-to-reverse choice (datastore, framework, auth model, sync vs. async, monorepo vs. polyrepo) and want the reasoning captured before it's forgotten.
- You're starting an ADR log in a repo that has none, or adding the next record to an existing
docs/adr/directory. - A pull request changes architecture and a reviewer asked "where is this written down?"
- You're revisiting an old decision and need to supersede it with a new record instead of silently editing history.
[!NOTE] An ADR is immutable once merged. You don't edit a decision to change it — you write a new ADR that supersedes it and flip the old one's status to
Superseded by ADR-NNNN. Editing the substance of a merged record erases the history the log exists to preserve.
Instructions
- Locate the ADR log. Search for an existing directory —
docs/adr/,docs/decisions/,doc/adr/, oradr/. Read one or two existing records to match the local heading set, status vocabulary, and front-matter (some logs useMADR, someNygard, some carry adate:/deciders:block). If no log exists, default todocs/adr/. - Assign the number and slug. Find the highest existing
NNNN-*.mdand increment it, zero-padded to four digits (0001,0002, ...). Build the filename asdocs/adr/NNNN-kebab-title.mdfrom a short, decision-focused title (0007-use-postgres-for-primary-store.md). Never reuse or renumber an existing file. - Detect the real constraints — don't invent them. Mine the repo for evidence that shaped the decision instead of writing generic pros and cons:
- Read
package.json/requirements.txt/go.mod/Cargo.tomlfor the current stack and what's already a dependency. - Grep for the systems in play (
grep -ri "mongoose\|prisma\|pg\|sqlalchemy") to see what's actually wired up. - Check
docker-compose.yml,*.tf, CI config, and anyREADME/CLAUDE.mdfor deployment targets, scale signals, and stated team conventions. - Note the requirement that forces the decision (transactions, relational queries, a managed offering already in the cloud account, an existing team skillset).
- Read
- Write the record. Use the Nygard section order:
# NNNN. Title, then## Status,## Context,## Decision,## Consequences(split into positive and negative — be honest about the costs you're accepting), and## Considered Alternatives(an added section not in Nygard's original — list each rejected option with the specific reason it lost). Write in past/decided tense, name concrete tradeoffs, and cite the constraints from step 3 rather than restating textbook definitions. - Set the status deliberately. Use
Proposedfor an open decision under review,Acceptedonce it's agreed,Deprecatedfor an outdated record, orSuperseded by ADR-NNNNwhen replaced. If this record retires an older one, update that file's status line to point here. - Verify and report. Confirm the filename number is unique, the title slug matches the heading, and every alternative has a stated reason for rejection. List the file you wrote, and flag any section you filled from assumption rather than repo evidence so the user can correct it before merging.
[!WARNING] Don't pad the Consequences with only upsides. An ADR that lists no negative consequences is a sales pitch, not a decision record — the reviewer can't weigh a tradeoff you hid. Name the lock-in, the operational cost, or the capability you gave up.
Examples
For the decision "choose Postgres over MongoDB for the primary datastore," the skill detects no mongoose/prisma is wired yet, sees a managed Postgres already in the cloud account, and writes docs/adr/0001-use-postgres-as-primary-datastore.md:
# 0001. Use PostgreSQL as the primary datastore
## Status
Accepted — 2026-06-03
## Context
The billing and account services need ACID transactions across orders,
invoices, and ledger entries, and most read paths join three or more
entities. Our data is strongly relational with a stable schema. The team
already operates a managed Postgres instance in the existing cloud account
and knows SQL; no one has run MongoDB in production here.
## Decision
We will use PostgreSQL 16 as the primary datastore for all transactional
services, accessed through a single connection pool per service. Document-
shaped, schemaless data (audit blobs, webhook payloads) will live in
`jsonb` columns rather than a separate document database.
## Consequences
**Positive**
- Multi-row transactions and foreign keys enforce invariants in the
database instead of in application code.
- One datastore to operate, back up, and monitor — reuses the managed
instance and the team's existing SQL skills.
- `jsonb` covers the few semi-structured cases without a second system.
**Negative**
- Horizontal write scaling requires deliberate work (partitioning, read
replicas) if write volume outgrows a single primary.
- Schema changes need migrations and review; less forgiving than a
schemaless store during rapid early iteration.
## Considered Alternatives
- **MongoDB** — rejected: our access patterns are relational and need
cross-document transactions, which fight against its document model and
would push join logic into the application.
- **Postgres + a separate document DB** — rejected: doubles operational
surface for a small amount of semi-structured data that `jsonb` handles.
- **SQLite** — rejected: no managed multi-writer story for our concurrency
and availability needs.After writing, report the path and note any section (e.g. projected write volume) that came from an assumption rather than a measured constraint, so the user can verify it before merging.
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.

