How to use the UX Spec Review agent skill (ux-review)

What is an agent skill, and what does ux-review make the agent do?

An agent skill is a folder containing a SKILL.md file that tells Claude how to perform one kind of task. When the skill is active, the agent follows the checklist in that file instead of improvising.

The ux-review skill reads a UX design document and checks it against a detailed checklist. The checklist covers completeness (required sections such as Purpose & Player Need, States & Variants and Acceptance Criteria), input method coverage for keyboard, gamepad and touch, data ownership, accessibility, and alignment with game design documents (GDDs). It then returns one of four verdicts: APPROVED, NOT ASSESSED, NEEDS REVISION or MAJOR REVISION NEEDED, with the specific gaps listed.

• NOT ASSESSED means a dimension had nothing to check against, or the spec could not be read. The skill names which dimension.
• NEEDS REVISION means specific gaps to fix before handoff, not a full redesign.
• MAJOR REVISION NEEDED means fundamental problems with scope, player need or completeness.

Install the ux-review skill

Download the ZIP for this skill from this page and unzip it. The skill folder contains SKILL.md. Put the folder in one of two places: your user skills folder at ~/.claude/skills/ so it is available in every project, or a project's .claude/skills/ folder so it applies only to that project.

If you use the Claude apps instead of Claude Code, you can upload the skill under Settings → Capabilities → Skills.

• User-wide: ~/.claude/skills/ux-review/
• Single project: .claude/skills/ux-review/ inside the project folder

Trigger the skill with a natural request

You can invoke the skill with the argument shown in its hint: a file path, 'all', 'hud' or 'patterns'. The skill also accepts plain requests. If you give no argument, it asks which spec to validate.

For a file path, the skill validates that single document. For 'all', it scans design/ux/ and validates each file, starting with a summary table (file, verdict, primary issue).

• /ux-review design/ux/inventory.md
• /ux-review hud
• /ux-review patterns
• /ux-review all
• Review my inventory UX spec before I hand it to the UI programmer.

Know what the review needs to work well

The checks depend on project files. The skill loads the platform settings from project.yaml (or falls back to .claude/docs/technical-preferences.md), the accessibility tier from design/accessibility-requirements.md if it exists, the pattern library at design/ux/interaction-patterns.md, the GDDs referenced in the spec header, and design/player-journey.md if present.

Without written UX specs or GDDs, the review has little or nothing to check and will be marked NOT ASSESSED. The skill is built around the Claude Code Game Studios workflow and the /ux-design and /team-ui pipeline, so it is not useful for non-game software.

• Requires Claude Code, with access to the repository's hooks/yaml-helper.sh script and .claude/docs config files
• Optional: project.yaml, design/accessibility-requirements.md, design/ux/ specs, GDD files

Check the safety notes before running it

This skill runs a script: its allowed tools include a bash helper, hooks/yaml-helper.sh, which it uses to resolve configuration. The skill is limited to reading files, searching with Glob and Grep, and that one helper. The source does not describe any network access, and the skill is listed as not using the network.

Read SKILL.md and hooks/yaml-helper.sh before you install it into a shared repository, so you know what runs on your machine.

• Runs scripts: yes (yaml-helper.sh, configuration resolution only)
• Uses network: no
• Use the skill on your own repository files; it reads specs and GDDs to check them

Tips for getting useful verdicts

Set up the input methods and accessibility tier before you review. The input method checks follow platform.targets, platform.primary_input, gamepad_support and touch_support in project.yaml, not the spec header, so a spec header that is wrong will not hide a missing gamepad section.

Give the skill the GDD files your spec references. Every GDD UI Requirement named in the header is cross-checked, and missing ones show up as gaps.

Run it before the Pre-Production to Production gate, where key screens need reviewed UX specs, and again after major revisions.

• Use the verdict as a to-do list: fix each listed gap, then rerun the review.
• Keep the file path explicit when you are unsure which checklist applies. Files with a Template header are classified by that header; others are classified by file name.