Ask an agent to "write an ADR" with no skill loaded and you get something that looks right and rots fast. It invents a section layout that doesn't match the three-digit-numbered files already sitting in docs/decisions/. It records a decision with a confident rationale and no alternatives, so the record reads as an assertion rather than a choice. Asked to document a decision made two years ago, it happily fabricates the reasoning nobody can remember. And asked for a "microservices patterns" doc, it returns a bulleted glossary of Saga and Circuit Breaker that could have been written without ever seeing your system. A skill's job is to stop each of those failures before it reaches a file.
The surprising part, after reading the ones collected here, is how little the star count tells you. The highest-starred entry is a tidy but ordinary Nygard template; the most exacting workflow in the set carries two-digit stars. The best of these skills don't treat an ADR as a form to fill. They treat it as a governed artifact: they refuse to draft from thin evidence, demand two independent sources before backfilling a past decision, and write each decision's links in two places because ADR graph tools read two different places. That is the difference worth installing for.
Top picks
| skill | publisher | license | verdict | updated |
|---|---|---|---|---|
| adr-author | microsoft | MIT | Enforces the full template through hard gates and scripts | 2026-07-28 |
| adr-drafting | JosiahSiegel | MIT | Argues you toward a defensible decision, one question at a time | 2026-06-18 |
| adr-backfill | JosiahSiegel | MIT | The honest way to record a decision already shipped | 2026-06-18 |
| architecture-decision-records | wshobson | MIT | Five worked templates; teaches, doesn't enforce | 2026-07-22 |
| documentation-and-adrs | addyosmani | MIT | Broader docs skill that matches your repo's convention first | 2026-07-26 |
Start with Microsoft's adr-author when you want the process enforced, not suggested
Microsoft's adr-author runs a Frame → Decide → Govern state machine with gates that actually stop the agent. The Decide phase rejects a single-option ADR and rejects one with no documented downside; neither advances. Output is either a compact Y-Statement or a MADR v4.0.0 record, and its adopt-template mode ingests your team's existing ADR file so the format matches what's already in the repo instead of a fresh invention. Before any write, a sensitive-content script scans for PII, and a lineage allocator is the sole writer of the next decision id, so supersession links update atomically.
The cost is weight. This skill expects the surrounding ADR Creator agent, state.json files, and a stack of referenced instruction files; direct invocation works but you are adopting machinery, not a one-file helper. If you want the strictest guarantees, this is the pick.
Reach for JosiahSiegel's adr-drafting to be argued with, not autocompleted
adr-drafting co-writes the record through a seven-phase dialogue, one question per turn. You list the options, not the agent; it refuses to advance until you name two or three ways the decision fails in production, and it rejects "the team" as a decider in favor of a named human. It self-critiques the draft against an "ADR is not" checklist before you ever see it. Its sharpest detail: it mirrors every relationship into both YAML frontmatter and a body ### Relationships block, because ADR graph tools split into frontmatter-only parsers and body-scanning parsers — write one surface and half your tooling renders no edges.
The catch is that it sits in the middle of a pipeline. It won't draft without a confirmed discovery brief and routes you upstream to adr-discovery, whose zero-hallucination rule turns every code finding into a question before it becomes a fact.
Use JosiahSiegel's adr-backfill for decisions already shipped but never written down
adr-backfill exists for the exact failure that sinks most retroactive ADRs: inventing a rationale nobody recorded. It refuses to draft unless you supply two independent evidence locators — a commit plus a migration file, a removed module plus a retired flag — and refuses outright when reconstruction confidence is low, because the "why" would have to be fabricated. Every backfill carries a mandatory honesty clause so a future reader can't mistake it for a contemporaneous record, and it takes the next available number rather than faking a past one.
Other writers mention this in passing — govctl's tells you to distinguish recovered evidence from inference in a sentence. This one makes that its whole job, and its sibling adr-critique flags any backfill whose honesty clause was stripped.
Keep wshobson's architecture-decision-records for the templates when you don't want a process
architecture-decision-records is the reference shelf. It hands you five fully worked templates — standard MADR, a lightweight variant, a Y-Statement, a deprecation record that supersedes an earlier one, and an RFC — plus a when-to-write-versus-skip table, the adr-tools commands for init/new/supersede, and a review checklist. The PostgreSQL example is filled end to end, so an agent has a concrete shape to imitate rather than an abstract spec.
What it doesn't do is enforce anything. Nothing here stops your agent from emitting a one-option, no-downside ADR; the "consider all options" line is a checklist item, not a gate. Treat it as scaffolding for an agent you already trust to self-police, or pair it with one of the gated skills above.
How do you tell two skills with the same name apart?
You can't from the name — and the name is where most people stop. Skills are community-published and names aren't namespaced, so the same string routinely covers different documents, and sometimes different tools.
"adr-writer" is the clean example. Four skills carry that name, all MIT-licensed, and they are four different things. oxbshw's is a typed micro-tool with declared inputs and outputs that writes to a memory/decisions/ path and updates a MEMORY.md index — great if you use that convention, odd if you don't. Mathews-Tom's is a six-phase workflow with conditionally loaded reference files and calibration rules ("a decision without context is just an assertion"). govctl's is a governance-CLI helper with hard stops — it won't even set an ADR's status, deferring that to its govctl tooling and RFCs. patricio0312rev's is a single worked template with a TimescaleDB example, anti-patterns, and two checklists. Same name, same license, and installing the wrong one drops a foreign directory convention into your repo.
It gets starker with generic topics. Search "microservices patterns" and you'll find wshobson's — a short navigation page that defers its depth to a references/ file — alongside near-verbatim copies of that same overview under other publishers, their stars ranging from the tens of thousands down to single digits. The name is the topic. The publisher and the body are the identity. Read the body, and note who shipped it.
What to check before you install one
Two things the card won't tell you.
License first. Several ADR skills here carry no license or a NOASSERTION flag — you can read them, but forking one into your own repo puts you on murky ground. For anything your agent will copy, adapt, or redistribute, prefer the MIT and Apache-2.0 ones. Every skill spotlighted above is MIT for that reason.
Stars second, and lower than you'd think. The highest star count in this space belongs to affaan-m's architecture-decision-records at 234207 — a perfectly competent Nygard-format skill with decision-detection signals and a confirm-before-write step, but no more rigorous than several others here, and its number reflects the mega-repo it ships inside, not the skill. Microsoft's gated authoring skill sits at 1299, and JosiahSiegel's pipeline at 49. If you want the convention-matching angle without a full ADR engine, addyosmani's documentation-and-adrs inspects the repo for an existing .adr-dir or MADR layout and surfaces the conflict rather than silently starting a second scheme — a good default for a codebase that already has some decisions written down.
What you have now
The four failures from the top of this page each have an owner. The invented layout is handled by adr-author's adopt-template mode and addyosmani's convention-matching. The assertion-with-no-alternatives is caught by adr-drafting's option and failure-mode gates, and by adr-author's hard reject of single-option records. The fabricated backfill is exactly what adr-backfill refuses to produce without two independent sources. And the generic patterns doc is what reading the body — not the star count — lets you avoid. Install adr-author or adr-drafting for new decisions, adr-backfill for the ones already shipped, and keep wshobson's templates on the shelf. Then check the license and the publisher before any of them touch your repo.
More skills worth a look
ADR Drafting helps teams document significant architectural decisions by creating new Architecture Decision Record files with a standard structure. It inspects your repository for existing ADR conventions, then drafts a new record with Title, Status, Context, Decision, and Consequences sections—defaulting to `docs/architecture/adr` when no convention exists.
architecture-decision-recordThis skill provides templates and guidance for creating Architecture Decision Records—lightweight documents that preserve the reasoning behind major technical choices. It walks you through the Nygard format, covering context, decision, consequences, and alternatives, plus best practices for lifecycle management and team review. Use it when evaluating trade-offs or recording decisions that shape your system's future.
adr-decision-extractionThis skill scans conversations, session transcripts, and design discussions to isolate architectural decisions—capturing problem statements, chosen options, alternatives considered, and decision drivers. It recognizes explicit `[ADR]` tags alongside implicit choice patterns and trade-off debates, then rates each decision's confidence level. Output feeds directly into ADR writing tools rather than generating documents itself.
write-adrWrite ADR captures architectural decisions from your conversation and generates formatted Architecture Decision Records automatically. It orchestrates the full workflow—extracting decisions, confirming selections with you, writing ADRs in parallel, and verifying output against quality standards.
develop-adrThis skill guides you through creating an Architecture Decision Record that captures the reasoning behind significant technical or architectural choices. It follows Michael Nygard's lightweight format to ensure decisions are documented with their context, rationale, and trade-offs—preserving institutional knowledge for future team members. Use it when selecting technologies, establishing development patterns, or documenting constraints that shape your system.
030-architecture-adr-generalThis skill guides you through creating Architecture Decision Records for Java projects via structured dialogue. It systematically gathers decision context, stakeholder input, and architectural trade-offs, then produces a MADR-formatted document capturing your choice and rationale.
architecture-selectionArchitecture Selection helps teams pick the best system design by evaluating patterns against team size, domain complexity, scaling needs, and operational maturity. It scores candidates using weighted criteria, documents trade-offs, and provides migration paths—avoiding resume-driven choices and premature optimization. Use it to design new systems, plan migrations, or review existing architectures.
architectureArchitecture helps you build decision records for technology choices, system designs, and architectural proposals. It structures your analysis across options, trade-offs, and consequences—whether you're choosing between platforms like Kafka and SQS, reviewing a microservices design, or building a new component from requirements.
architecture-designerArchitecture Designer guides you through system design from requirements to documented decisions. It creates architecture diagrams, evaluates technology trade-offs, and produces Architecture Decision Records for key choices. Use it to structure microservices, plan scalability, and validate designs with stakeholders.
software-architecture-designMake informed architecture decisions for new systems or major refactors. This skill guides you through pattern selection, scalability design, resilience strategies, and data consistency models—with concrete technology recommendations and tradeoff analysis. Covers decomposition, service boundaries, observability planning, and migration from legacy systems.
adr-authorADR Author guides you through writing Architectural Decision Records that future developers and automated systems can actually enforce. It covers the full workflow from reading existing ADRs to drafting decisions at the right enforceability level—whether you need automated verification, human review, or reference-only documentation.
doc-adrdoc-adr captures a single architectural decision using the Context-Decision-Consequences pattern, positioned as Layer 5 in the specification-driven development flow. It records the rationale, chosen approach, evaluated alternatives, and accepted trade-offs for decisions that bridge container and component design.