Unity CLI Skill — AI-Powered Unity Editor Automation for Claude Code

Claude Code · Codex · Cursor · Gemini CLI — official Unity channels only, no third-party editor plugins

English | 简体中文

Drive the Unity Editor with AI, through official Unity channels only — no third-party editor plugins, no MCP server.

This is a Claude Code skill built on the official Unity CLI and the com.unity.pipeline package. It teaches your AI agent to:

• 🧱 Edit scenes live — create/delete/modify GameObjects, components, transforms, materials, prefabs (140+ built-in commands)
• 🔍 Read the Editor — console logs, scene hierarchy, serialized fields, performance stats
• 🧪 Run tests — EditMode/PlayMode, connected or headless, with NUnit XML reports
• 📦 Build players — headless batch builds (Android APK/AAB, iOS, Standalone, WebGL)
• ⚡ Eval arbitrary C# — batch 20 operations into one sub-second call, no domain reload
• 📸 Self-verify with screenshots — the agent captures the Game view, looks at it, and iterates

Everything in this skill was verified against a real Unity 6 project — every command name, parameter format, latency number, and pitfall was tested, not copied from docs.

Why the official CLI?

	Unity CLI (this skill)	Third-party REST/MCP plugins
Maintained by	Unity	Community
Editor plugin required	Only com.unity.pipeline (official)	Third-party package
Headless tests & builds	✅ Built in	Usually not
Arbitrary C# eval	✅ Built in	Varies
Survives domain reload	✅ (verified)	Often breaks

Requirements

• Unity 6.0+ project (required by com.unity.pipeline)
• Unity CLI (beta):
  • Windows: irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex
  • macOS/Linux: see the official install docs
• Claude Code

Quick start

# 1. Install the skill (project-level, or use ~/.claude/skills/ for global)
git clone https://github.com/ZHAO0424/unity-cli-skill.git <your-workspace>/.claude/skills/unity-cli

# 2. Log in and install the Pipeline package into your Unity project
unity auth login
unity pipeline install --project-path <your-unity-project>

# 3. Open a Claude Code session and just ask:
#    "Create 10 cubes in a circle and screenshot the result"
#    or invoke explicitly with /unity-cli

What's inside

File	Content
SKILL.md	Core playbook: connected vs. headless decision tree, command syntax, eval batching, security model, verification loop, verified known-issues table
references/xr-recipes.md	XR playbook: XR Origin rig setup, XRGrabInteractable wiring, ray-interactor debugging, hand tracking, world-space UI rules, an XR scene health-check eval, simulator gotchas
references/pipeline-commands.md	All 140 built-in commands, grouped by domain, generated from a live editor
references/eval-snippets.md	High-frequency C# eval snippets (one-shot objective health check, missing-reference scan, batch edits, DDOL queries…)
references/build-and-deploy.md	Build → adb install → on-device acceptance loop, plus three field-tested build pitfalls (stale assemblies, externally overwritten assets not reimporting, serialized defaults vs. scene instances)
references/verify-before-trust.md	The method this playbook was built with: empirically attack a plan's factual basis before implementing (--help every command, re-test every second-hand claim, check for environment drift)
references/project-context-template.md	Template for your project's own CLAUDE.md — the skill handles the channel, your CLAUDE.md holds the project knowledge

What this is / isn't

This is a channel layer, by design. Your agent host (Claude Code etc.) already reads code, greps architecture, and holds project memory — this skill deliberately does not duplicate any of that. It makes one thing reliable: operating the Unity Editor. So you won't find a project indexer, a script relationship graph, or a task pipeline engine here — your agent composes those from its native tools plus this channel, and your project's own CLAUDE.md supplies the project knowledge (template included).

Security model

Honest version: this skill is documentation, not a sandbox — eval runs with the editor process's privileges, same trust level as giving your agent a terminal. The real guardrails:

1. Clean git state before any bulk-edit session — version control is the only reliable undo.
2. Enforcement belongs to the host: Claude Code users can gate Bash(unity command eval*) with permission rules — that's a mechanism; prompt constraints are not.
3. Narrow the write scope with set_authoring_root (e.g. Assets/AgentWork) for generation tasks.
4. Destructive built-ins require confirm=true and support dry_run; the skill forbids bypassing them via eval.

If you don't accept the eval trade-off, use built-in commands only and deny eval at the host level.

Verification loop (objective first, screenshot last)

The skill's acceptance recipe runs cheap, unambiguous checks first — console error count, a one-shot missing-reference/missing-script health check, relevant tests, performance stats — and only then takes a Game view screenshot for the agent to look at, judging what objective checks can't: composition, mood, interaction states. For XR scenes there's an extra XR health check (canvas distance ≥ 0.5 m, interactables have colliders, XRInteractionManager present).

Highlights from the field-tested playbook

• Two modes, one rule: editor open → connected mode (:7800, sub-second, no domain reload); editor closed → headless one-shots. Never run headless against a project whose editor is open (project lock).
• Fight the ~0.8s/call latency: merge multi-step operations into a single eval — one call creates 10 objects and saves the scene.
• Windows Git Bash gotcha: MSYS rewrites leading-slash args (/Root/Cube → C:/Program Files/Git/...). Drop the leading slash or set MSYS_NO_PATHCONV=1.
• unity build has no built-in pipeline — --execute-method is mandatory; point it at a static build method in your project.
• Destructive ops are gated: built-ins require confirm=true and support dry_run — the skill forbids bypassing them via eval.
• The screenshot self-verification loop: capture → the agent reads the image → compares against acceptance criteria → iterates. No human needed to describe what's on screen.

Works with other AI agents & platforms

The underlying layer — Unity CLI + com.unity.pipeline — is AI-agnostic and runs on Windows, macOS, and Linux. Only the auto-loading mechanism is Claude Code-specific; the playbook content works with any LLM agent that can run shell commands:

Agent	How to use
Claude Code	Clone into .claude/skills/unity-cli/ — auto-loads (this repo's native format)
OpenAI Codex CLI	Clone anywhere in your workspace — the included AGENTS.md points the agent at SKILL.md
Cursor	Reference SKILL.md from .cursor/rules
Gemini CLI	Reference SKILL.md from GEMINI.md

macOS/Linux notes: the Git Bash path-rewriting gotcha in SKILL.md is Windows-only; everything else (latency, focus behavior, project lock, eval syntax) is platform-neutral.

Version pinning

Tested baseline: Unity CLI 1.0.0-beta.3 + com.unity.pipeline 0.4.0-exp.1 (2026-08). Both are beta/experimental — after upgrading, run the verification checklist at the bottom of SKILL.md.

SKILL.md and the references are currently written primarily in Chinese. Claude reads them natively regardless of your conversation language — an English edition is on the roadmap. PRs welcome.

License

MIT