create-architectural-decision-record

Use it when:: You've made, or are proposing, an architecture decision and want it recorded in a standard format.
It does:: Takes the title, context, decision, alternatives and stakeholders from you or the conversation, asks for anything missing, and fills a fixed ADR template.
You get:: /docs/adr/adr-NNNN-title-slug.md, numbered after the last ADR, with status Proposed and coded items such as POS-001, NEG-001 and ALT-001.

TL;DR

An ADR, or architectural decision record, is a short document that captures one design decision: why it was needed, what was chosen and what it costs. This command writes one in a fixed format meant for both people and AI tools to read. It needs five inputs, a title, the context, the decision, the alternatives and the stakeholders, and asks you for any it can't find in the conversation before writing. The file goes in /docs/adr/ as adr-NNNN-title-slug.md, where NNNN is the next four-digit number. Its front matter holds the title, status, date, authors, tags and supersedes and superseded_by links. The body has the status (Proposed, Accepted, Rejected, Superseded or Deprecated, starting at Proposed), the context, the decision with its rationale, positive and negative consequences, each alternative with the reason it was rejected, implementation notes on rollout and monitoring, and references. Multi-item sections use coded bullets such as POS-001 or IMP-002.

Summarizes the skill at 797337f.

npx skills add https://github.com/github/awesome-copilot --skill create-architectural-decision-record

skills.sh page Source on GitHub All skills from github/awesome-copilot

Total Downloads: 10,300 on skills.sh, Nov 9, 2026
Repo stars: 40,943 github/awesome-copilot
First seen: Feb 25, 2026 on skills.sh

Weekly Downloads

-11% over the 8 weeks to Nov 9

Weekly values

Week to	Installs
Sep 21	47
Sep 28	39
Oct 5	51
Oct 12	27
Oct 19	27
Oct 26	34
Nov 2	37
Nov 9	42

Category	category:planning category:writing category:software-engineering Make the agent question you and write the plan down before it writes code. Articles, docs, internal comms, research write-ups and prose that doesn't read as generated. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills.
Type	type:command A one-shot action you invoke by name, such as turning the conversation into a PRD.
Effect	effect:local Its own steps create or change files, git state or local tools.
Needs	needs:none Instructions only. Works in any agent that supports skills.
Publisher	by:official A verified publisher on skills.sh, or the company or maintainer behind the product the skill operates.
Topics	architecture docs-writing

SKILL.md

From github/awesome-copilot at 797337f. Checked daily, last changed Nov 6, 2026.

Frontmatter

name: create-architectural-decision-record
description: 'Create an Architectural Decision Record (ADR) document for AI-optimized decision documentation.'

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:

---
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]