How to use the Pascal Architecture Reviewer agent skill

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 with instructions that an AI agent loads when a request matches the skill's description. This skill is named review-architecture and its SKILL.md is the only file listed for it.

When triggered, the agent first reads the project's architecture wiki pages, such as layers.md, node-definitions.md and viewer-isolation.md, before looking at any code. It then fetches a pull request diff or the current branch diff and classifies every new file, type, store field or exported helper by package: core, viewer, editor or nodes. Finally it runs a checklist covering the node composition model, hook usage and selector performance. The output points out likely violations and flags serious ones as blockers.

Install the skill from the ZIP

Download the ZIP for this skill from the page, then unzip it. To make the skill available to all your projects, place the review-architecture folder in ~/.claude/skills/. To make it available only inside one project, place it in that project's .claude/skills/ folder.

You can also 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/
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Prepare your environment

The skill needs git and the GitHub CLI (gh), and gh must be authenticated so it can read PR diffs and file lists. It also needs a checkout of the pascalorg/editor repository, because the skill reads the wiki/architecture documents and DECISIONS.md from that checkout. Without them the review rules are not available to the agent.

• git installed
• GitHub CLI (gh) installed and authenticated
• A local checkout of pascalorg/editor containing wiki/architecture/ and DECISIONS.md

Trigger the skill with natural requests

You do not need a special command. Ask for a review in plain language. The skill's description covers requests to review a PR, audit a branch, or check that changes respect the codebase's architecture. Give a PR number or URL when you have one, or say you want the current branch reviewed.

The skill's own instructions say the user will provide a PR URL, a branch name, or ask to review the current branch. Be specific about the scope so the agent reads the right diff.

• Review PR 123 against the Pascal architecture rules.
• Audit my current branch for package boundary violations.
• Check that this branch respects the codebase's architecture before I open a PR.
• Review https://github.com/pascalorg/editor/pull/<number> for architecture problems.

What the review checks

The checklist covers package boundaries (core, viewer, editor, nodes), the registry-driven composition model using def.geometry, def.renderer and def.system, legacy-dispatch regressions, the slots and world-scale-UV convention for new nodes and geometry, hook hygiene for useEditor, useScene and useViewer, and selector performance.

The skill's instructions ask the agent to do the layer classification before the checklist, because wrong-package code is the most common and most damaging violation. The agent reads additional wiki pages when a diff touches their subject, such as scene-runtime.md for core store changes or interaction-scope.md for tool files.

Safety notes: scripts and network access

The skill does not run scripts. It does use the network: the agent calls gh to fetch PR diffs and file lists. Its allowed tools are limited to git, gh, Read, Grep and Glob, as listed in the skill's metadata.

Because the skill reads PR content through gh, check that your gh login has the access you intend the agent to have.

• Runs scripts: no
• Uses network: yes, through gh and git commands
• Allowed tools: git, gh, Read, Grep, Glob

Tips for getting useful results

Treat the output as a checklist-driven first pass. The skill can miss or misjudge violations, so a human should make final merge decisions.

Run the review on a branch that is up to date with main, since the skill diffs against main. Check the flagged blockers against the cited wiki page before acting on them.

• Keep your pascalorg/editor checkout current so the wiki rules match the code.
• Expect the skill to be most useful for changes that add new files, store fields or tools.
• Use it before opening a PR to catch layer mistakes early.