writing-adrs
This skill guides you through writing Architecture Decision Records—concise documents that capture the shape of load-bearing choices, why you made them, and what trade-offs you considered. Use it when a decision is hard to reverse, surprising without context, or the result of genuine alternatives. ADRs live in docs/adr/ with sequential numbering and a simple template; most need just a paragraph.
Writing ADRs helps you document architectural decisions in docs/adr/ with a minimal template and clear criteria for when they matter.
AI-generated summary based on this skill's SKILL.md
Decision gist · record as of 2026-07-27
Writing ADRs helps you document architectural decisions in docs/adr/ with a minimal template and clear criteria for when they matter. This skill guides you through writing Architecture Decision Records—concise documents that capture the shape of load-bearing choices, why you made them, and what trade-offs you considered. Use it when a decision is hard to reverse, surprising without context, or the result of genuine alternatives. ADRs live in docs/adr/ with sequential numbering and a simple template; most need just a paragraph.
Use it when
- writing-adrs recommends creating an ADR when a decision qualifies as load-bearing: it's hard to reverse, surprising without explanation.
- writing-adrs teaches the standard ADR structure: sequential numbering in docs/adr/, a title, and core sections for Context (the problem).
Verify before relying
Read SKILL.md below before installing (1 file). Open directory: indexed for reading, not audited.
Similar skills
Install
frankify-app/skills/writing-adrs · repository language: Shell
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to write architecture decision records?
writing-adrs guides you through creating Architecture Decision Records that capture load-bearing choices, their rationale, and trade-offs. Start with a sequential number in docs/adr/, use the simple template (Context, Decision, Consequences), and keep most ADRs to a single paragraph. Focus on decisions that are hard to reverse, surprising without context, or chosen among genuine alternatives.
When should I create an ADR?
writing-adrs recommends creating an ADR when a decision qualifies as load-bearing: it's hard to reverse, surprising without explanation, or the result of weighing real alternatives. Skip ADRs for routine choices or reversible experiments. If you're unsure whether a decision needs recording, the skill helps you apply these criteria to decide.
What is the ADR template and format?
writing-adrs teaches the standard ADR structure: sequential numbering in docs/adr/, a title, and core sections for Context (the problem), Decision (what you chose), and Consequences (trade-offs and impact). Optional sections like Status and examples are available. Most ADRs fit in a paragraph; the template keeps them concise and scannable.
How does writing-adrs handle ADR numbering and organization?
writing-adrs covers ADR numbering and organization in docs/adr/. Each record gets a sequential number (0001, 0002, etc.) as its filename. The skill explains how to structure your docs/adr/ folder, maintain the sequence, and keep records discoverable and linked for teams reviewing architectural decisions.
What optional ADR sections does writing-adrs include?
writing-adrs teaches when to include optional sections like Status (Proposed, Accepted, Superseded) and Consequences in your Architecture Decision Records. These sections add context for decisions that need tracking or have complex downstream effects. The skill helps you decide which optional elements fit your decision's scope and audience.
What qualifies as an architecture decision for an ADR?
writing-adrs defines ADR-worthy decisions as those that are hard to reverse, surprising without context, or chosen among alternatives. Examples include tech stack choices, major refactors, and trade-off decisions. The skill helps you distinguish load-bearing architectural choices from routine implementation details that don't need formal recording.
SKILL.md
Rendered from the published skill. Quoted content, verbatim.
Writing ADRs
ADRs live in docs/adr/ and use sequential numbering: 0001-slug.md, 0002-slug.md, etc.
Create the docs/adr/ directory lazily — only when the first ADR is needed.
Template
# {Short title of the decision}
{1-3 sentences: what's the context, what did we decide, and why.}
That's it. An ADR can be a single paragraph. The value is in recording that a decision was made and why — not in filling out sections.
As short as possible — caveman mode preferred (caveman skill). Hard limit: precision and understandability must not suffer.
Optional sections
Only include these when they add genuine value. Most ADRs won't need
(truncated - see the full file via the links below)
File tree — 1 file
original/writing-adrs/SKILL.md
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Write or format an architecture decision record following best practices”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
Domain Modeling helps you actively construct and refine your project's domain model by establishing canonical terminology and recording architectural decisions. It guides you to challenge vague language, stress-test domain relationships with concrete scenarios, and maintain a glossary of precise, implementation-free terms that your team can reference.
This skill captures architectural decisions made during coding sessions as structured ADR documents that live alongside your codebase. It detects decision moments, gathers context and alternatives, and maintains a searchable log so future developers understand the reasoning behind your architecture.
ADR 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.
Write 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.
This skill generates Architecture Decision Records (ADRs) that capture the context, decision, and consequences of significant technical choices. It guides you through gathering essential information, selecting from three formats (MADR, Nygard, or Y-Statement), and produces a structured document that preserves reasoning for future engineers.
This skill guides you through authoring Architecture Decision Records (ADRs) that capture major technical choices with full context. It validates decisions against existing architectural stances, engine compatibility, and GDD requirements, then generates a structured record with status, dependencies, and consequences tracked. Use it to retrofit missing sections into existing ADRs or create new ones from scratch.
More skills Adr Skill (unlicensed)