How to use the Architectural Code Review agent skill (code-review)

What is an agent skill and what does this one make the agent do?

An agent skill is a folder containing a SKILL.md file that gives an AI agent specific instructions for a task. When you ask your agent to review code, this skill makes it check the files against a fixed checklist rather than writing a free-form opinion.

The checklist covers three areas. Coding standards include doc comments on public methods and classes, cyclomatic complexity under 10 per method, no method longer than 40 lines (excluding data declarations), injected dependencies rather than static singletons for game state, and configuration loaded from data files. Architecture rules include correct dependency direction, no circular dependencies between modules, proper layer separation so UI does not own game state, and events or signals for cross-system communication. SOLID checks cover single responsibility, open/closed, Liskov substitution, interface segregation and dependency inversion.

If the project keeps architecture decision records (ADRs), the skill also looks for ADR references in the story file, the header comments of the implementation files and git commit messages, then checks whether the code follows the referenced decisions. Deviations are classified as ARCHITECTURAL VIOLATION (blocking), ADR DRIFT (warning) or MINOR DEVIATION (info).

Install the code-review skill from a ZIP file

Download the ZIP for the skill from this page and unzip it. The folder you get contains SKILL.md. Where you put it depends on how you want to use it.

For a personal install available across your projects, unzip the skill into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder so it is shared with everyone who works in the repository.

If you use the Claude apps instead of the command line, you can upload the skill in Settings, then Capabilities, then Skills.

• Personal install: ~/.claude/skills/code-review/
• Project install: .claude/skills/code-review/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload

Check the requirements before you run it

This skill is designed for Claude Code working inside the Claude Code Game Studios project structure. It expects the hooks/yaml-helper.sh script and the .claude/docs files that the template provides. It also needs bash for its configuration helper script and git, because ADR lookup reads commit history.

The skill runs scripts and does not use the network. Its allowed tools are Read, Glob, Grep, Agent, AskUserQuestion and a small set of git log and config-helper commands.

• Claude Code
• Claude Code Game Studios project structure (hooks/yaml-helper.sh and .claude/docs files)
• bash
• git

How to trigger a review with a natural request

The skill takes an optional path argument: a file or a directory. You can invoke it directly, or describe what you want in ordinary words and let the agent select the skill.

If you want to add ADR checking to a file review, include the story file path as the last argument. The skill reads that story to find the governing ADR reference.

• Review Assets/Scripts/Combat/Attack.cs against our coding standards
• Do an architectural review of the combat folder and check it against SOLID
• Check the inventory system code against the ADRs
• Review this file for dependency direction and testability

Read the output honestly: NOT ASSESSED is a valid result

The skill is strict about missing inputs. Before producing a report, it records whether each input it needs is FOUND or ABSENT. If a required input is missing, the affected section is reported as NOT ASSESSED rather than filled with an invented clean result. If every required input is missing, the whole verdict is NOT ASSESSED, and the report names what was missing.

This matters for reading results. A green result from a scan that had no files to scan has verified nothing, and the skill is designed to say which situation occurred.

• Engine validation is reported as NOT ASSESSED when no engine is configured in project.yaml
• ADR Compliance reports NO ADRS FOUND when no references exist, which is different from NOT ASSESSED
• Findings are expected to include file and line, quoted evidence and a confidence level

Safety notes: scripts and what they touch

The skill runs a configuration helper script, resolve_config from hooks/yaml-helper.sh, when it loads. Read the SKILL.md and the script before installing it in a shared repository, so you know what runs on your machine. The skill does not use the network.

Review the findings yourself before acting on them. The skill is instructed to verify specialist findings before reporting them, but a report is still a reasoned judgement, not a guarantee.

Tips for useful reviews

Narrow the scope. A single file or one folder gives more precise findings than the whole repository. Provide the story path when your team uses ADRs, since without it the ADR check relies on references found in code and commits.

Keep the studio folder structure intact. Removing hooks, docs or project.yaml will leave setup steps and referenced docs missing, and those parts will be reported as not assessed.

• Start with one file to see the report format
• Add the story path to enable full ADR compliance review
• Expect NOT ASSESSED where your project lacks the expected files