Guide · Agent skill
How to use the Architecture Review agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Architecture Review skill is an agent skill for game projects that use the Claude Code Game Studios framework. It makes the agent check that your architecture decision records (ADRs) cover every requirement in your game design documents (GDDs), that the decisions do not conflict with each other, and that they match your pinned game engine version. This guide explains what an agent skill is, how to install this one, how to trigger it with plain requests, and how to read the verdict it returns.
Architecture ReviewDonchitos/Claude-Code-Game-Studios · MIT Download the skill Quick start
- 1Download the ZIP. Download the architecture-review ZIP from this skill's page in the directory.
- 2Unzip into a skills folder. Unzip into ~/.claude/skills/ for all projects, or into the project's .claude/skills/ for one project.
- 3Confirm the project files exist. Make sure the project has GDD documents, ADRs, an architecture document, and a pinned engine version.
- 4Ask for a review. Use a plain request such as asking for an architecture review, or name a focus like coverage or engine.
- 5Read the matrix. Review the traceability matrix the agent shows before approving any write.
- 6Approve or hold the writes. Choose write now, show full draft first, or not yet when the agent asks.
- 7Act on the verdict. Treat PASS, CONCERNS, NOT ASSESSED or FAIL as advisory and decide the next step yourself.
What is an agent skill and what does this one do?
An agent skill is a folder containing a SKILL.md file and supporting reference files. When it is installed, the agent can load these instructions and follow them for a specific kind of task. This skill is one of those folders.
Once installed, the agent acts as a quality gate for a game project's architecture. It reads the game design documents and architecture decision records, builds a traceability matrix that links each design requirement to the decision covering it, and looks for missing coverage, conflicting decisions, and mismatches with the pinned game engine version. It then returns a PASS, CONCERNS, NOT ASSESSED, or FAIL verdict.
- Traceability: each GDD requirement is matched to the ADR that addresses it.
- Gap detection: requirements with no covering ADR are flagged.
- Conflict detection: decisions that contradict each other across ADRs are flagged.
- Engine compatibility: decisions are checked against the pinned engine version.
- Output: a report, and an updated traceability index, written only after you approve.
Install the Architecture Review skill
You can install the skill in one of two ways. Download the ZIP from the skill's page in this directory, then either unzip it into your user skills folder or into a project's skills folder. Use ~/.claude/skills/ to make the skill available in all your projects, or .claude/skills/ inside a single project to limit it to that project.
If you use the Claude apps instead of Claude Code, you can upload the ZIP under Settings → Capabilities → Skills.
- Personal (all projects): unzip into ~/.claude/skills/ so the folder becomes ~/.claude/skills/architecture-review/.
- Single project: unzip into the project's .claude/skills/ folder.
- Claude apps: upload the ZIP under Settings → Capabilities → Skills.
~/.claude/skills/architecture-review/Check what the project needs before you run it
The skill expects a game project built on the Claude Code Game Studios framework. It reads existing files rather than creating them from nothing, so the project must already contain its design and architecture documents. A project with no written game design documents or ADRs has nothing to trace, and the review will not be useful.
The skill runs helper scripts, so it needs a Bash shell. The helper scripts it names are yaml-helper.sh, review-receipts.sh, adr-dep-graph.sh and registry.sh, which live in the surrounding .claude/ framework rather than in this skill folder. The skill does not use the network.
- Claude Code or a compatible agent runtime.
- A Bash shell for the helper scripts.
- GDD documents, ADRs, an architecture document, and a pinned engine version in the project files.
- Read-only checks run without writing; writes need your approval.
How do you trigger the skill with a natural request?
You can ask for a full review in plain language, or name a focus. The skill accepts these modes: full (the default when no argument is given), coverage (which GDD requirements have no ADR), consistency (cross-ADR conflicts only), engine (engine compatibility only), single-gdd with a path to one GDD, and rtm (a Requirements Traceability Matrix that adds story and test file paths).
Use rtm only in the Production phase, when stories and tests exist. The argument hint for the skill is: [focus: full | coverage | consistency | engine | rtm | single-gdd path/to/gdd.md].
- "Run an architecture review on this project."
- "Check which game design requirements have no ADR yet."
- "Look for conflicting decisions across our ADRs."
- "Check our architecture against the pinned engine version."
- "Review the architecture for the combat GDD only."
What do the verdicts mean and what does the output look like?
The review ends with one of four verdicts: PASS, CONCERNS, NOT ASSESSED, or FAIL. The skill describes the verdict as advisory. You decide whether to continue, even when it reports CONCERNS or FAIL.
Before anything is written, the agent shows the full traceability matrix and the content of any proposed file in the conversation. It then asks for approval through a structured question with options to write now, show a full draft first, or not yet.
- PASS, CONCERNS, NOT ASSESSED, FAIL are the four verdict labels named in the skill.
- The report and traceability index are written only after you approve.
- In collaborative mode (the default), the agent asks before writing.
Safety notes: scripts and what they can touch
The skill runs helper scripts through Bash. Its allowed commands are limited to specific helper calls such as yaml-helper.sh resolve_config, review-receipts.sh check and hash, adr-dep-graph.sh, and registry.sh validate. It can read, search and write files, but writes follow the approval step described above.
Because it can write files, review the draft before approving, and keep your project under version control so you can see and revert any change.
- The skill makes no network calls.
- It runs local Bash helper scripts; read the scripts in .claude/ before first use if you want to confirm what they do.
- It can miss issues in files it does not read, so treat the verdict as input, not sign-off.
Tips for getting a useful review
Keep GDDs and ADRs current before you run the review, because the matrix is only as accurate as the documents it reads. Run a focused mode such as coverage or single-gdd first if the project is large, then run full once the gaps are understood.
Answer the agent's clarifying questions carefully. When a requirement is ambiguous, the skill asks whether it is a technical requirement or a design preference, and that answer changes the verdict.
- Start with coverage on a large project.
- Use single-gdd to review one system at a time.
- Use rtm only once stories and tests exist.
- Read the advisory verdict as a prompt to investigate, not a final decision.
What people use it for
- Checking that every combat or economy requirement in a GDD has a covering ADR before pre-production.
- Finding two ADRs that make contradictory decisions about the same system.
- Confirming that architecture decisions match the pinned engine version.
- Generating a requirements-to-stories-to-tests matrix during production using rtm mode.
- Reviewing one GDD at a time on a large project with single-gdd.
Frequently asked questions
How do I install the architecture-review skill?
Download the ZIP from this skill's page and unzip it into ~/.claude/skills/ to use it in all projects, or into a project's .claude/skills/ folder to use it in one project. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills.
Is the architecture-review skill free to use?
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 before you reuse it.
What do I need to run it?
You need Claude Code or a compatible agent runtime, a Bash shell for the helper scripts, and project files from the Claude Code Game Studios framework, including GDD documents, ADRs, an architecture document, and a pinned engine version.
Does it work on a non-game project?
No. The workflow is built around game design documents and game engine compatibility, so it is not suited to non-game software.
What do the PASS, CONCERNS, NOT ASSESSED and FAIL verdicts mean?
They are the four verdict labels the skill returns. The skill describes the verdict as advisory, so you decide whether to continue even after CONCERNS or FAIL. Read the traceability matrix to see which requirements drove the result.
Does the skill make changes without asking?
No. In the default collaborative mode, it shows the matrix and the draft content first, then asks for approval before writing the report or traceability index.
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 run a game project on the Claude Code Game Studios framework and want a traceability check between design documents and architecture decisions before pre-production or during production. Pick something else if your project is not a game, or if you have no written GDDs or ADRs, since there is nothing for the skill to trace.
Download the skill