Guide · Agent skill
How to use the Architecture Decision Records agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The architecture-decision skill is an agent skill for Claude Code that helps you record a technical decision as an Architecture Decision Record (ADR), a numbered markdown document covering the context, the alternatives you considered and the consequences. This guide explains what the skill makes the agent do, how to install it, how to trigger it with plain requests, and what to check before you rely on it. By the end you will be able to write a new ADR, retrofit one for an existing decision, and move an ADR to Accepted.
Architecture Decision RecordsDonchitos/Claude-Code-Game-Studios · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or your project's .claude/skills/ folder.
- 2Check the project layout. Make sure the project has a docs/architecture/ folder and an ADR numbering scheme.
- 3Ask for a new ADR. Ask the agent to record a decision and give a short title, such as event-system-architecture.
- 4Answer the questions. Describe the context, the alternatives you considered and the consequences when the agent asks.
- 5Review the generated file. Check the ADR written to docs/architecture/ before committing it. It is created as Proposed.
- 6Accept when settled. Run /architecture-decision accept ADR-NNNN once a human has settled the decision.
What is an agent skill and what does this one do?
An agent skill is a folder of instructions and optional scripts that Claude Code loads when a task matches it. This skill, architecture-decision, is meant for recording a technical decision. When you ask the agent to record one, it walks you through the context, the options you considered and the consequences, then writes the ADR into your project's docs/architecture folder.
The skill can also retrofit an ADR for a decision already made in existing code, or mark an existing ADR as accepted. It is built for game-studio workflows, so it reads engine context and can spawn review agents such as a technical director to check the decision. New ADRs stay in Proposed status until a human accepts them.
- Creates a new numbered ADR in docs/architecture/ with context, alternatives and consequences.
- Retrofits an ADR for a decision that exists only in code.
- Accept mode moves an existing ADR from Proposed to Accepted.
- Can spawn review agents such as a technical director to check the decision.
Install the architecture-decision skill
There are two ways to add the skill. Download the ZIP from the skill's page on this directory and unzip it. For a personal install, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder, so the skill lives at .claude/skills/architecture-decision.
Alternatively, upload the ZIP 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 the ZIP.
What the skill needs before it runs
The skill expects Claude Code with the skill installed under .claude/skills/architecture-decision. It needs Bash access for the config helper script yaml-helper.sh, and optionally registry.sh. It also expects project files such as docs/architecture/ and the .claude/docs files it references. Some reference files may be missing from the package, so the skill can behave less completely in that case.
The skill expects a docs/architecture folder and an ADR numbering scheme. Without that convention, it may create files in unexpected places.
- Claude Code with the skill at .claude/skills/architecture-decision.
- Bash access for yaml-helper.sh and optional registry.sh.
- A docs/architecture/ folder and numbered ADR files (adr-NNNN-name.md).
- Project files referenced by the skill, such as .claude/docs.
How to trigger the skill with natural requests
Ask the agent in plain language to record a decision. The skill takes an optional argument: a title for a new ADR, retrofit followed by a file path, or accept followed by an ADR id. You can also add --review with full, lean or solo.
If you give no title, the skill asks what decision you are documenting and suggests a short title such as event-system-architecture.
- Record a new decision: ask for an ADR about your decision and give a short title.
- Retrofit: ask to retrofit an existing ADR file, for example docs/architecture/adr-0001-event-system.md.
- Accept: ask to accept a specific ADR id, for example ADR-0005.
/architecture-decision [title | retrofit <path> | accept <ADR-id>] [--review full|lean|solo]Examples of what to ask for
A typical new-decision session starts with a title, then the agent gathers context and asks you to compare options. Because it asks many questions first, reserve it for decisions that deserve a formal record.
For a decision made in code long ago, use retrofit on the existing file so the missing sections can be checked. When a decision is settled, use accept so the ADR moves from Proposed to Accepted.
- New decision: /architecture-decision event-system-architecture
- Retrofit a legacy record: /architecture-decision retrofit docs/architecture/adr-0001-event-system.md
- Accept a settled decision: /architecture-decision accept ADR-0005
/architecture-decision event-system-architectureSafety notes: scripts and network
The skill runs scripts: yes. It uses Bash for the config helper yaml-helper.sh and the optional registry.sh, and it is limited to specific Bash commands in its allowed tools. It does not use the network. Review the scripts in your project before running the skill on sensitive code.
The skill writes and edits files in your project, so check the generated ADR before committing it.
- Runs scripts: yes (yaml-helper.sh, optionally registry.sh).
- Uses network: no.
- Review ADR output before committing.
Tips for getting good results
Keep the ADR in Proposed until a human has reviewed the alternatives. The skill is designed to collaborate and will not decide architecture on its own. Run /architecture-review in a fresh session, not the same one, so the review is independent of the authoring context.
Use it for significant choices, not quick one-off coding questions, since a full formal document is overhead for small decisions.
- Keep new ADRs Proposed until a person accepts them.
- Run /architecture-review in a fresh Claude Code session.
- Use it for significant decisions, not small ones.
What people use it for
- Documenting an event system or physics engine choice so the team can find the reasoning later.
- Retrofitting an ADR for an architecture choice that was made in code but never recorded.
- Linking ADRs to design docs in a Claude Code Game Studios setup.
- Getting a technical director review agent to check a proposed decision.
Frequently asked questions
How do I install the architecture-decision skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for a personal install, or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
What does the architecture-decision skill require?
It requires Claude Code with the skill installed at .claude/skills/architecture-decision, Bash access for yaml-helper.sh and optionally registry.sh, and project files such as docs/architecture/. Some reference files may be missing from the package.
Is the architecture-decision skill free?
The skill is listed under the MIT licence. The source does not state any price, so check the licence text on the source repository for terms.
Does the skill use the network?
No. The skill is listed as not using the network, but it does run scripts, so review yaml-helper.sh and registry.sh before running it on sensitive code.
Why does the skill ask so many questions?
It produces a full formal document covering context, alternatives and consequences, so it gathers that information first. For small one-off choices this is overhead, and a quick coding question is better handled without it.
Can the skill decide architecture for me?
No. It is designed to collaborate and leaves the ADR in Proposed status until a human accepts it. Use accept mode once the decision is settled.
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 you are a developer or tech lead who wants decisions written in a consistent numbered format, especially if you use the Claude Code Game Studios setup or need to document a choice that exists only in code. Skip it for quick coding questions, for projects without a docs/architecture convention, or if you want an agent to make architecture decisions on its own.
Download the skill