Create Architectural Decision Record
Generate a numbered ADR markdown file in /docs/adr/ with structured alternatives, consequences, and coded bullets after you decide an architecture choice.
Overview
create-architectural-decision-record is an agent skill most often used in Build (also Validate scope) that writes AI-friendly ADR markdown files with alternatives and consequences under /docs/adr/.
Install
npx skills add https://github.com/github/awesome-copilot --skill create-architectural-decision-recordWhat is this skill?
- Standardized ADR template with front matter, context, decision, and alternatives
- Sequential naming adr-NNNN-title-slug.md under /docs/adr/
- Coded bullet scheme (3–4 letter codes + 3-digit numbers) for machine-friendly sections
- Input validation—asks for missing Context, Decision, Alternatives, or Stakeholders before writing
- ADR path convention /docs/adr/ with adr-NNNN 4-digit sequential filenames
- Coded bullet format uses 3–4 letter codes plus 3-digit numbers for multi-item sections
Adoption & trust: 9.2k installs on skills.sh; 34.6k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You made an architecture call in chat but have no sequential, parseable ADR in the repo for teammates or future agents.
Who is it for?
Indie teams documenting why Postgres beat SQLite, or why you chose a specific agent framework, before complexity compounds.
Skip if: Exploratory brainstorming with no decision yet, or organizations that mandate a different ADR tool outside markdown in /docs/adr/.
When should I use this skill?
You need an Architectural Decision Record document for a titled decision with context, alternatives, and stakeholders.
What do I get? / Deliverables
A complete adr-NNNN-slug.md file is saved with validated inputs, coded sections, and documented trade-offs.
- adr-NNNN-[title-slug].md with front matter and consequence sections
- Documented rejection rationale for each alternative
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Architecture decisions are captured as durable repo docs during Build—docs subphase is the canonical home for ADR artifacts. ADRs belong beside implementation docs so agents and future-you can parse decisions without re-deriving context from chat.
Where it fits
Record why you narrowed from three auth vendors before building the prototype.
Publish adr-0004-message-queue-selection.md after implementing the worker.
Attach an ADR link in the PR description so reviewers see rejected alternatives.
How it compares
Structured ADR generator—not a general wiki or Notion export skill.
Common Questions / FAQ
Who is create-architectural-decision-record for?
Solo builders and small teams who want lightweight, version-controlled decision logs inside their git repo.
When should I use create-architectural-decision-record?
After Validate when locking scope on stack choices; during Build when adopting a new service boundary; before Ship when reviewers need written rationale for risky migrations.
Is create-architectural-decision-record safe to install?
It writes documentation files under your repo when invoked—review the Security Audits panel on this Prism page and your filesystem permissions policy.
SKILL.md
READMESKILL.md - Create Architectural Decision Record
# Create Architectural Decision Record Create an ADR document for `${input:DecisionTitle}` using structured formatting optimized for AI consumption and human readability. ## Inputs - **Context**: `${input:Context}` - **Decision**: `${input:Decision}` - **Alternatives**: `${input:Alternatives}` - **Stakeholders**: `${input:Stakeholders}` ## Input Validation If any of the required inputs are not provided or cannot be determined from the conversation history, ask the user to provide the missing information before proceeding with ADR generation. ## Requirements - Use precise, unambiguous language - Follow standardized ADR format with front matter - Include both positive and negative consequences - Document alternatives with rejection rationale - Structure for machine parsing and human reference - Use coded bullet points (3-4 letter codes + 3-digit numbers) for multi-item sections The ADR must be saved in the `/docs/adr/` directory using the naming convention: `adr-NNNN-[title-slug].md`, where NNNN is the next sequential 4-digit number (e.g., `adr-0001-database-selection.md`). ## Required Documentation Structure The documentation file must follow the template below, ensuring that all sections are filled out appropriately. The front matter for the markdown should be structured correctly as per the example following: ```md --- title: "ADR-NNNN: [Decision Title]" status: "Proposed" date: "YYYY-MM-DD" authors: "[Stakeholder Names/Roles]" tags: ["architecture", "decision"] supersedes: "" superseded_by: "" --- # ADR-NNNN: [Decision Title] ## Status **Proposed** | Accepted | Rejected | Superseded | Deprecated ## Context [Problem statement, technical constraints, business requirements, and environmental factors requiring this decision.] ## Decision [Chosen solution with clear rationale for selection.] ## Consequences ### Positive - **POS-001**: [Beneficial outcomes and advantages] - **POS-002**: [Performance, maintainability, scalability improvements] - **POS-003**: [Alignment with architectural principles] ### Negative - **NEG-001**: [Trade-offs, limitations, drawbacks] - **NEG-002**: [Technical debt or complexity introduced] - **NEG-003**: [Risks and future challenges] ## Alternatives Considered ### [Alternative 1 Name] - **ALT-001**: **Description**: [Brief technical description] - **ALT-002**: **Rejection Reason**: [Why this option was not selected] ### [Alternative 2 Name] - **ALT-003**: **Description**: [Brief technical description] - **ALT-004**: **Rejection Reason**: [Why this option was not selected] ## Implementation Notes - **IMP-001**: [Key implementation considerations] - **IMP-002**: [Migration or rollout strategy if applicable] - **IMP-003**: [Monitoring and success criteria] ## References - **REF-001**: [Related ADRs] - **REF-002**: [External documentation] - **REF-003**: [Standards or frameworks referenced] ```