Guide · Agent skill
How to use the Create Architectural Decision Record agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide explains how to use the create-architectural-decision-record agent skill, a set of instructions that tells an AI agent how to write an Architectural Decision Record (ADR) for a technical choice made during a conversation. It is written for people who have not used agent skills before. By the end you will know what the skill does, how to install it, how to ask for an ADR in plain language, and where it falls short.
Create Architectural Decision Recordgithub/awesome-copilot · MIT Download the skill Quick start
- 1Download the skill. Download the skill ZIP file from this page.
- 2Unzip it into a skills folder. Unzip into ~/.claude/skills/ for personal use or into the project's .claude/skills/ folder for one project.
- 3Or upload it in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
- 4Describe the decision. Explain the decision, the context, the alternatives you considered and the stakeholders involved.
- 5Answer any follow-up questions. If the agent is missing a required detail, it will ask for it before writing the record.
- 6Check the file location and number. Confirm the file was saved in /docs/adr/ as adr-NNNN-[title-slug].md with the correct next number.
- 7Update the status. A new record starts as Proposed. Change it to Accepted or another status once the team has decided.
What is an agent skill and what does this one do?
An agent skill is a folder containing a SKILL.md file that gives an AI agent specific instructions for a task. This skill covers one task: recording a technical decision as an Architectural Decision Record.
When you ask the agent to record a decision, it gathers the context, the decision made, the alternatives considered and the stakeholders involved. It then writes a standardised ADR as a Markdown file in a docs/adr folder, so future team members can see why a choice was made.
- Front matter with title, status, date, authors, tags, supersedes and superseded_by fields
- Status, Context and Decision sections
- Positive and negative consequences, each with coded IDs such as POS-001 and NEG-001
- Alternatives considered, each with a description and a rejection reason
- Implementation notes and references
Install the skill
Download the ZIP file for the skill from this page. Unzip it into one of these locations, depending on how you want to use it: ~/.claude/skills/ makes the skill available to you across projects, while a project's .claude/skills/ folder makes it available only within that project.
You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload
How to trigger the skill with a natural request
You do not need a special command. Describe the decision in a normal request and say that you want it recorded as an ADR. Include the decision title if you have one, since the skill uses it as the basis for the file.
If the agent cannot find a required detail in the conversation, it will ask you for it before writing the file. This covers the title, context, decision, alternatives and stakeholders.
- Record an ADR for our choice of PostgreSQL over MongoDB for the orders service, including the alternatives we rejected.
- Write an architectural decision record for moving our CI pipeline to GitHub Actions.
- Document the decision to use Redis for session caching as an ADR.
What the output looks like
The skill asks for a file named adr-NNNN-[title-slug].md in the /docs/adr/ directory, where NNNN is the next sequential four-digit number. For example, the first record would be adr-0001-database-selection.md. The file starts with front matter and follows a fixed template, so records look the same across a repository.
The template uses coded bullet points (3-4 letter codes followed by three-digit numbers) for multi-item sections, which makes individual points easy to cite and search.
adr-0001-database-selection.mdSafety, requirements and limits
The skill lists no requirements. It does not run scripts and does not use the network. It works by writing a Markdown file based on the conversation.
The skill hard-codes the /docs/adr folder and sequential numbering. If your repository uses a different ADR folder or numbering scheme, the output may create duplicates or be placed in the wrong location. Check the folder and the next number before accepting the file.
The template is heavyweight. For quick notes or small implementation choices, a formal record is probably more than you need.
- No requirements are listed for this skill
- Runs scripts: no
- Uses network: no
- Check that /docs/adr is the right folder and that the number does not clash with an existing record
Tips for better ADRs
The quality of the record depends on the detail in the conversation. State the constraints, the options you actually weighed and who was involved before asking for the record. Review the status field: a new record is marked Proposed, and you will need to change it to Accepted or another status yourself once the team agrees.
- Give the context and constraints in your first message, not as an afterthought
- Name the alternatives you rejected and why, so the rejection reasons are filled in
- List stakeholders by role or name so the authors field is accurate
- Review the file before committing it
What people use it for
- Recording a database choice, such as selecting PostgreSQL for a service, with the rejected options listed
- Documenting a framework decision so new developers can see why it was chosen
- Logging an infrastructure choice made during a planning conversation
- Creating a searchable history of architectural decisions in a repository that already uses /docs/adr
Frequently asked questions
How do I install the create-architectural-decision-record skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
Does this skill need any requirements or dependencies?
The skill lists no requirements. It does not run scripts and does not use the network, so it works by writing a Markdown file from the conversation.
Is the create-architectural-decision-record skill free?
The skill is published under the MIT licence, as stated on this page. Check the licence file in the source repository for the full terms.
Where does the skill save the ADR file?
It saves the file in the /docs/adr/ directory with the name adr-NNNN-[title-slug].md, where NNNN is the next sequential four-digit number.
Can I use this skill if my repository uses a different ADR folder or numbering?
This is a poor fit. The skill hard-codes /docs/adr and sequential numbering, which may create duplicates or misplaced files. Adjust the output manually or choose a different skill.
What should I do if the agent asks me for more information?
The skill is designed to ask for missing required details such as the title, context, decision, alternatives or stakeholders before writing. Provide the missing details in your reply so the record is complete.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if your team wants a consistent, searchable log of significant technical decisions, especially in a repository that already keeps records in /docs/adr. Skip it for small implementation choices, or if your repository uses a different ADR folder or numbering scheme, since you would have to fix the output by hand.
Download the skill