How to use the UX Design Spec agent skill (ux-design)

What the ux-design skill makes the agent do

An agent skill is a folder containing a SKILL.md file and supporting reference files. When you ask for a matching task, the agent loads the skill and follows its instructions instead of improvising. This skill is for game UX documentation.

The agent first asks what you are designing. It then reads your existing player journey and project design docs for context before writing anything. It fills in each section of a template one at a time, saving progress to the file as it goes, so work survives interruptions. It also checks cross-references with related docs and suggests which specialist roles to coordinate with, such as art-director, ui-programmer or accessibility-specialist.

• Screen or flow spec: written to design/ux/ under the name you give (for example main-menu becomes design/ux/main-menu.md).
• HUD design: written to design/ux/hud.md.
• Interaction pattern library: written to design/ux/interaction-patterns.md.
• Accessibility requirements: written to design/accessibility-requirements.md, outside design/ux/ on purpose, because other project checks look for it at that path.

Install the ux-design skill

Download the ux-design ZIP from this page. Unzip it into one of two locations, depending on how you want to use it.

For all your projects, unzip it into ~/.claude/skills/. For one project only, unzip it into that project's .claude/skills/ folder. The skill folder should be named ux-design so it appears as the ux-design skill.

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

• Claude Code or another compatible SKILL.md agent is required.
• The repository's .claude/docs folder must be present in your project, because the skill reads guides and config from it.
• Keep the skill's scripts in place. The skill calls a helper script at hooks/yaml-helper.sh one level above the skill folder.

Check what the skill needs before you start

The skill has a few hard requirements. It expects a game project that uses this studio's file layout, with design docs in the design/ and docs/ folders. Without those, the agent may create or look for files in the wrong places.

It also needs a bash shell so its config-resolution helper can run. The skill's source states that it runs scripts and does not use the network.

• Requires: Claude Code or a compatible SKILL.md agent, the .claude/docs folder, and a bash shell.
• Runs scripts: yes, the config-resolution helper.
• Uses network: no.
• Not suited to non-game UI or web product design, since the templates and modes assume a game structure.

Trigger the skill with a natural request

You can invoke the skill with an argument or simply describe the task. The argument options are a screen or flow name, hud, patterns, or accessibility. If you give no argument, the agent asks what you are designing and offers the options.

Name the screen in plain words; the agent converts it to kebab-case for the filename. Be specific about whether you want a screen spec, the HUD, the pattern library or accessibility requirements, because each writes to a different file.

• Design the inventory screen for this game.
• Write the HUD design for our game.
• Start the interaction pattern library.
• Write the project-wide accessibility requirements.
• Help me figure out which UX docs we need next.

Work through a session with the agent

The agent works section by section. For each section it states what the section needs, asks questions, offers options where there are design choices, drafts the section, and waits for your approval before writing it to the file. Nothing is written to the file without your sign-off in the default collaborative mode.

If a session is interrupted, the agent reads its session state file and the output file, then resumes from the first incomplete section. Sections marked [To be designed] still need work.

• Depth of each section follows the docs.density setting: terse (default), balanced or thorough.
• Which screens must have a spec depends on the workflow setting: full, standard or minimal.
• Specialist agents return analysis, but only the main session writes files.

Safety notes: scripts and what the skill can touch

The skill can read, search, write and edit files, and it can run one bash helper script, hooks/yaml-helper.sh, with its resolve_config command. Read the script before you rely on it in a sensitive project. The skill does not use the network, according to its source.

The skill writes design documents into your project's design/ folder. Review those files before committing them, and keep your project under version control so you can see and revert changes.

• Allowed tools include Read, Glob, Grep, Write, Edit, AskUserQuestion, Agent and the one bash helper command.
• Check the design/ paths the skill will create before you approve a skeleton file.
• Use a test branch or copy the project first if you are unsure how the skill will interact with existing docs.

Tips for getting good output

Give the agent a player journey and game concept first, because it reads those before asking questions. Use the same argument names each time so the agent targets the right file.

Pick the depth you need before you start. Terse output is the default; switch to balanced or thorough only when a section needs more prose.

• Keep design/gdd/game-concept.md or design/game-brief.md up to date; the agent warns if neither exists.
• Approve sections one at a time rather than batching, so you catch problems early.
• Ask the agent to check cross-references after finishing a spec.