adr-author
Skill1 starsChanged 4 months agoMITView on GitHub
Use when the user wants to write, draft, or create an Architectural Decision Record (ADR) — capturing an architecture or technical decision, recording why a choice was made, or documenting a decision for the team. Guides framing a sharp Context/Decision/Consequences and drives the AdrMcp MCP tools (create_adr, validate_adr) to produce a well-formed MADR record. Triggers on "write an ADR", "record this decision", "create a decision record", "document this architecture choice", "we decided to…".
7 other projects use a version of this.
Adopted by
Most recently taken up by
- kevin-burns/claude-skillstheir own version, first seen Nov 15, 2026
- 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
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
- kevin-burns/claude-skills★ 11same name
- Bioconductor/ai-agent-skills★ 10same name
- rajanrx/skills★ 2same 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 repository3 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- adr-reviewSkill
- adr-supersedeSkill
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 4 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 6 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 24
Don't write an ADR for reversible, local, or obvious choices (variable names, a one-off bug fix, formatting).
- Very specific: line 29
Check for overlap: Call list_adrs (or search_adrs) so you don't duplicate or silently contradict an existing decision.
- Distinctive: line 47
Context states the problem, not the answer: If the context already names the chosen tool, it's decision-leakage — rewrite it around the …
- Distinctive: line 51
Consequences are honest: Every real decision has costs.
- Distinctive: line 54
Keep it tight: an ADR is a memo, not an essay.
“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
Authoring an ADR
You help the user turn a real architectural decision into a crisp, durable ADR. The MCP server handles mechanics (numbering, files, frontmatter, validation) — your job is the judgment and prose: is this decision worth recording, and is it framed honestly?
Requires the AdrMcp MCP server (tools
create_adr,validate_adr,list_adrs). If those tools aren't available, tell the user to connect the AdrMcp server first.
Does this decision even warrant an ADR?
Record it when the decision is architecturally significant — it constrains future work and would be expensive to reverse. Good signals:
- It affects structure, dependencies, interfaces, or cross-cutting concerns.
- A future contributor will ask "why is it done this way?" and deserve an answer.
- Reasonable engineers would have chosen differently; there were real alternatives.
Don't write an ADR for reversible, local, or obvious choices (variable names, a one-off bug fix, formatting). If it doesn't constrain the future, skip it and say so.
Workflow
- Check for overlap. Call
list_adrs(orsearch_adrs) so you don't duplicate or silently contradict an existing decision. If one exists, consideradr-revieworadr-supersedeinstead of a new record. - Interview for the four parts (ask only what you can't infer from the codebase/context):
- Context / problem — the forces at play, constraints, what makes this non-trivial.
- Considered options — the real alternatives, not strawmen.
- Decision — the chosen option, stated as a decision ("We will…"), not a discussion.
- Consequences — what becomes easier AND what becomes harder / what we accept.
- Draft with
create_adr(template=madrdefault),previewOnly=truefirst so the user sees the diff. Passtagsfor the architectural area,decidersif known. - Validate with
validate_adron the new id; fix any errors (missing sections, dangling links) before committing. - Commit by re-calling
create_adrwithpreviewOnly=falseonce the user approves. - New ADRs start as
proposed. Useset_statusto move toacceptedonly when the decision is actually adopted.
Quality bar
- Context states the problem, not the answer. If the context already names the chosen tool, it's decision-leakage — rewrite it around the forces.
- The decision is falsifiable and specific. "Use PostgreSQL 16 for the primary store" beats "improve the database situation."
- Consequences are honest. Every real decision has costs. An ADR with only upsides is marketing, not a record — name at least one trade-off you're accepting.
- Alternatives were genuinely considered. List what you rejected and one reason why.
- Keep it tight: an ADR is a memo, not an essay. If a section is a placeholder, fill it or cut the ADR.
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.

