review-architecture — Claude Code skill: architecture doc review
review-architecture is a Claude Code skill that checks a written architecture artifact against the system it describes.
no license ★ 155 updated 2026-10-29
npx skills add serpro69/claude-toolbox --skill review-architecture -a claude-codeWhat review-architecture does
Point it at one committed artifact and it turns the prose into a set of claims. Each claim is then checked for whether the named mechanism exists and sits in the right place: module boundaries, who owns which data, NFR mechanisms, failure isolation, state consistency, versioning, binding to the domain. A second pass grades the decisions against the context the artifact states for itself.
The checking runs in a read-only architecture-reviewer subagent. The skill owns acceptance and presentation, so it relays the full claim table, the per-dimension verdicts and the Not Reviewed section. Compressing that report throws away the inspectable middle artifact the claim set exists to be.
One artifact per call: $kk:review-architecture <artifact-path>. Diagrams need prose beside them, and two paths at once are rejected. For a domain-reference kit, pass either page and the glossary/traps counterpart is found automatically. Runtime behaviour is not its job: that is $kk:review-code and $kk:review-spec. Security architecture goes to mcp__pal__secaudit.
What it helps with
- catch an ADR that names a mechanism the system does not have
- review a glossary and its traps page as one composite artifact
- get a verdict per dimension instead of a single overall grade
- judge how reversible a decision is before building on it
- route security architecture to
mcp__pal__secauditon its own track
Example prompts for the agent
- Run
$kk:review-architecture <artifact-path>on the ADR indocs/adr/and relay the report in full. - Review only the architecture section of the design doc under
docs/feat/wip/. - Review
docs/domain/<context>.mdas a composite together with its traps page.
How to install review-architecture
1Skills CLI (Vercel)
npx skills add serpro69/claude-toolbox --skill review-architecture -a claude-code2Manually: put the files in place
~/.claude/skills/review-architecture/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/review-architecture/
1Skills CLI (Vercel)
npx skills add serpro69/claude-toolbox --skill review-architecture -a codex2Manually: put the files in place
.agents/skills/review-architecture/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add serpro69/claude-toolbox --skill review-architecture -a cursor2Manually: put the files in place
.cursor/skills/review-architecture/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install serpro69/claude-toolbox kodex-plugin/skills/review-architecture2Manually: put the files in place
.github/skills/review-architecture/SKILL.md1Skills CLI (Vercel)
npx skills add serpro69/claude-toolbox --skill review-architecture -a gemini-cli2Platform CLI
gemini skills install https://github.com/serpro69/claude-toolbox --path kodex-plugin/skills/review-architectureManually: put the files in place
.devin/skills/review-architecture/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about review-architecture
How do I install review-architecture in Claude Code?
Run npx skills add serpro69/claude-toolbox --skill review-architecture -a claude-code. The skill lands in ~/.claude/skills/review-architecture/SKILL.md.
What does review-architecture do?
It splits an architecture document into claims, then verifies that each declared mechanism exists and is wired into the right topology. Decisions are graded against the context the document sets out for itself.
Does it check runtime behaviour?
No. It confirms a mechanism is present and correctly placed; what the code does under retries belongs to $kk:review-code and $kk:review-spec.