create-architectural-decision-record Skill for Claude: What It Does and How to Install It

Makes Claude write an Architectural Decision Record (ADR) as a markdown file with a fixed structure.

Installs: 10.2K; on skills.sh
Stars: 40.7K; on GitHub
Updated: Oct 2026; last repo commit

This skill is a template and a rule set for ADRs, from the community awesome-copilot collection. Claude takes a title, context, decision, alternatives and stakeholders, and asks for any that are missing.

It writes the ADR to /docs/adr/adr-NNNN-[title-slug].md, where NNNN is the next 4-digit number. The file has front matter and sections for status, context, decision, consequences, alternatives, implementation notes and references, with coded bullets such as POS-001 and NEG-001.

Good for

Engineers documenting why they chose a design
Tech leads keeping a decision log in the repo
Teams that want ADRs both people and AI tools can parse

Install create-architectural-decision-record

Claude Code

Copy this prompt.

Install the create-architectural-decision-record skill in Claude Code. Run this command:

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

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Create an Architectural Decision Record (ADR) document for AI-optimized decision documentation.

Sections in SKILL.md

Inputs
Input Validation
Requirements
Required Documentation Structure
Status
Context
Decision
Consequences
Positive
Negative
Alternatives Considered
[Alternative 1 Name]
[Alternative 2 Name]
Implementation Notes
References

Key facts

Author: GitHub (awesome-copilot community collection)
License: MIT (repo license from GitHub; SKILL.md states none)
Installs on skills.sh: 10,214 (Nov 2, 2026)
GitHub stars: 40,666 for the whole github/awesome-copilot repo (Nov 2, 2026)
Last repo commit: Oct 30, 2026
What it includes: 1 file: SKILL.md (no scripts or references)
Needs: Five inputs: decision title, context, decision, alternatives and stakeholders. Claude asks for any it cannot find in the conversation

What it includes

Five inputs; asks you for any that are missing
Needs the decision title, context, decision, alternatives and stakeholders, and asks before generating if any cannot be found in the conversation.
Try: “Write an ADR for choosing PostgreSQL over MongoDB for our orders service.”
Read · Input check
Precise language, both pros and cons, rejection reasons
Sets the writing rules: unambiguous wording, positive and negative consequences, alternatives with reasons, and coded bullets.
Read · Requirements
/docs/adr/adr-NNNN-[title-slug].md
Saves the file in the docs/adr folder with the next sequential 4-digit number, such as adr-0001-database-selection.md.
Write · Save location and naming
title, status, date, authors, tags, supersedes, superseded_by
Starts the file with these seven fields. Status is one of Proposed, Accepted, Rejected, Superseded or Deprecated.
Write · Front matter
Status, Context, Decision, Consequences, Alternatives, Implementation, References
Fills seven sections. Consequences split into POS and NEG items, alternatives use ALT items, implementation uses IMP and references use REF.
Write · Document sections

From the official docs

Permissions

Low risk

Claude creates a markdown file under docs/adr in your repo. Review it before you commit.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It writes a file in your repo
The ADR is saved under docs/adr with the next 4-digit number. Check the content and the file name before you commit. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	No read-only mode. Use version control.
Sign-in and keys	SKILL.md mentions no account or key.
Scopes	Claude creates one markdown file at /docs/adr/adr-NNNN-[title-slug].md

Questions

What does the create-architectural-decision-record skill do?

It makes Claude write an ADR for a design decision. The file follows one template with status, context, decision, consequences, alternatives, implementation notes and references.

How do I install it?

Use the install box at the top of this page. The skill is one SKILL.md file with no scripts.

Where does the ADR file go?

SKILL.md says to save it in the /docs/adr/ directory as adr-NNNN-[title-slug].md, with the next sequential 4-digit number.

What does it need from me?

A decision title, the context, the decision, the alternatives and the stakeholders. If Claude cannot find them in the conversation, SKILL.md tells it to ask before writing.

Why are the bullets coded like POS-001?

SKILL.md asks for coded bullets (a 3 to 4 letter code and a 3-digit number) in multi-item sections, so the file is easy for tools to parse and for people to reference.

Is it safe?

It bundles no scripts. Claude creates one markdown file in your repo under docs/adr. Review it before you commit.

Information

updated Nov 2, 2026

Repository: github/awesome-copilot
Folder: skills/create-architectural-decision-record

github/awesome-copilot skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 2

create-architectural-decision-record SKILL.md · github.com
github/awesome-copilot README · github.com