unity-cli skill
scriptsUnity CLI operating contract for every Unity task. Prove the exact project and Editor, choose CLI or built-in MCP transport, run Roslyn and focused test checks, apply ownership and risk gates, and install the official CLI safely. For idea-to-project setup use unity:new-unity-project.
- GitHub stars
- 13
- Files
- 20
- Last commit
- Oct 22, 2026
- License
- MIT
- Allowed tools
- 1
What does the unity-cli skill do?
unity-cli is an agent skill. Unity CLI operating contract for every Unity task. Prove the exact project and Editor, choose CLI or built-in MCP transport, run Roslyn and focused test checks, apply ownership and risk gates, and install the official CLI safely. For idea-to-project setup use unity:new-unity-project.
How to install the unity-cli skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the unity-cli skill in Plugin
/plugin marketplace add furkantokkan/agent-foundry /plugin install agent-foundry@agent-foundry
Install the unity-cli skill in Claude Code
~/.claude/skills/unity-cli/SKILL.md
$ npx degit furkantokkan/agent-foundry/plugins/agent-foundry/skills/unity-cli ~/.claude/skills/unity-cliInstall the unity-cli skill in Claude Code (project)
.claude/skills/unity-cli/SKILL.md
$ npx degit furkantokkan/agent-foundry/plugins/agent-foundry/skills/unity-cli .claude/skills/unity-cliInstall the unity-cli skill in Codex
~/.agents/skills/unity-cli/SKILL.md
$ npx degit furkantokkan/agent-foundry/plugins/agent-foundry/skills/unity-cli ~/.agents/skills/unity-cliInstall the unity-cli skill in Gemini CLI
~/.gemini/skills/unity-cli/SKILL.md
$ npx degit furkantokkan/agent-foundry/plugins/agent-foundry/skills/unity-cli ~/.gemini/skills/unity-cliInstall the unity-cli skill in Claude.ai
npx degit furkantokkan/agent-foundry/plugins/agent-foundry/skills/unity-cli unity-cli && zip -r unity-cli.zip unity-cli # claude.ai → Customize → Skills → + → Create skill → Upload a skill → unity-cli.zip
SKILL.md
View on GitHubUnity CLI
For every Unity task, first run the read-only project readiness check. It owns repository/instruction discovery, exact identity, dirty work, path and serialized ownership, Editor state, and verification readiness. Report its READY / READY WITH WARNINGS / BLOCKED verdict before dependent work. This is part of unity-cli, not a separate skill. Reuse a fresh readiness snapshot across nested skill calls for the same task. Revalidate when the target, identity, ownership, instructions, dirty work, or relevant Editor state changes; do not repeat the check solely because another skill was loaded.
Agent Foundry operating contract
The official unity@unity-agent-plugin also exposes unity:unity-cli for
Unity's domain procedure. Pair it with this Agent Foundry operating contract;
do not treat the duplicate short name as two independent transports or run a
mutation twice.
Use the installed unity CLI as the mandatory control plane for every Unity
task. Always start by verifying unity --version and the relevant command help;
for project work, read ProjectSettings/ProjectVersion.txt and apply the version
gate below before choosing live identity evidence. Unity 6+ uses
unity status --json; older supported Editors use the MCP identity gate.
This requirement also applies when the final implementation is an ordinary
source-file edit.
If unity is missing, install the official Unity CLI before continuing. The
user's standing instruction explicitly authorizes this one tool installation
when absent. Download the official installer to a temporary file, inspect it,
run it, and verify the installed binary; never pipe a remote response into a
shell. Environment-level network or elevation approval may still be required.
Do not bypass installation by switching to a legacy MCP transport.
On Unity 6+, the Pipeline package (com.unity.pipeline) is the default Editor
bridge for the CLI. When the project lacks it, install it with
unity pipeline install --project-path <root> --non-interactive under the
user's standing authorization for that one package addition
(Packages/manifest.json and the lock file Unity resolves). Install it in the
checkout that owns the Editor, never in a code lane, while no compile, test, or
Play Mode runs, then let the Editor resolve it and report the installed
version. It is Editor-only: never include it in runtime (see
Drive a running Unity Editor).
Upgrades, pins, removal, and commits keep their approval gates.
Transport order (apply the pre-Unity-6 version gate before this sequence):
- Unity CLI / Pipeline — use direct CLI commands for discovery, Editor control, project operations, tests, builds, and automation.
- Built-in
unity mcp— when an AI client requires MCP, start or configure the server through the installed CLI and pin it with--project-path. - Pinned source/file inspection — only after the applicable live transport has been checked and cannot safely expose the required state or operation. It is not proof of live Editor identity. Manual Unity YAML editing remains the last resort.
Legacy standalone Unity MCP connections and UnitySkills REST are not automatic
fallback transports. Use either only when the user explicitly requests it for
the current task. The one exception is the version gate in
Editor older than Unity 6.
Never perform the same mutation through two transports. When
using CLI Editor commands, pass the full --project-path and independently
match the returned canonical absolute project root and complete Unity version.
CLI path filters may use substring matching; the flag alone is not identity
proof. Never infer the target from a project name or the only returned row.
The installed CLI's help and current official Unity
documentation override this snapshot when flags or subcommands differ.
Editor older than Unity 6: MCP for Unity fallback
The Pipeline package (com.unity.pipeline) needs Unity 6.0+. When
m_EditorVersion in ProjectSettings/ProjectVersion.txt is below 6000.0
(for example 2022.3.x), the CLI cannot reach the live Editor.
unity status may report STATUS_NO_INSTANCES, and unity pipeline list
may show hasPipelinePackage: false. These are diagnostics, not proof of the
version gate, Editor absence, or target identity. Empty results can also reflect
Safe Mode, sandbox restrictions, missing packages, or connection failure. Do not run
unity pipeline install in that project. MCP for Unity (CoplayDev,
com.coplaydev.unity-mcp, Unity 2021.3+) is then the approved live-Editor
transport. The user does not need to request it for each task.
- Still verify
unity --version. Record the requested repository's canonical absolute root and completem_EditorVersionfromProjectVersion.txt(for example2022.3.62f2). Determine the gate from the numeric version, not a lexical comparison or a CLI error. Useunity pipeline list --jsononly as supporting diagnostics. A missing/unreadable version is unresolved, not permission to select a transport. Editors below MCP for Unity's supported minimum also need a compatible approved transport; do not infer support. - Keep the CLI for work that does not need a live Editor:
doctor,editors,logs,pipeline list,test,build, andrun.test,build, andrunneed the Editor closed because Unity locks the project. - Use MCP for Unity for live Editor control. Pin a release tag in
Packages/manifest.json:"com.coplaydev.unity-mcp": "https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#v10.2.0". Adding the package is still a package change and needs explicit target authorization. - Use server name
unityMCPover HTTP athttp://127.0.0.1:<port>/mcp. Take the port from the project'sAGENTS.md,.mcp.json, or.codex/config.toml. Do not assume a default. Start the server from the Unity MCP for Unity window. It runs throughuvx, souvmust be installed. Write it in project scope:.mcp.jsonfor Claude and[mcp_servers.unityMCP]in.codex/config.tomlfor Codex. Record the exception and the port in the projectAGENTS.md(andCLAUDE.md). MCP for Unity stores the HTTP URL in machine-wideEditorPrefs(MCPForUnity.HttpUrl), so another project can change it. If the server does not answer, check that the port in the window matches the project config. - Complete the exact MCP identity gate before
selecting or using any Editor, even when only one instance is connected.
When MCP for Unity's
unity-mcp-skillis installed, use it for tool workflows only after this gate passes. - Send each mutation through one transport only. When the project moves to Unity 6+, return to the CLI transport order and install Pipeline under the default above. Removing fallback packages/configuration still requires explicit target approval.
Exact MCP identity gate
- Discover without selecting. Read
mcpforunity://instances. Before callingset_active_instance, require fresh evidence tying exactly one listed full instance ID (and its session, when available) to both:- the requested repository's canonical absolute project root;
- the complete Unity version from that repository's
ProjectVersion.txt, including patch and suffix, not merely2022.3or6000. Resolve path separators, trailing separators, relative components, and symlinks/junctions before comparison; respect filesystem case sensitivity. Never use basename, substring, path-prefix, or worktree-parent matches.
- Require all identity fields. Use instance discovery fields when present,
or trusted read-only registration/process evidence explicitly bound to that
same full instance ID/session. A configured port, display name, hash/prefix,
remembered selection, or single connected Editor is not sufficient proof.
In MCP for Unity v10.2.0, HTTP discovery omits the full project path; do not
invent a
pathfield. If no independent instance-bound path/version evidence is available, returnBLOCKED: UNITY_TARGET_UNPROVENbefore selection. Do not read the default active Editor's state or select candidates in turn to discover which project they represent. - Pin only a unique proven match. Missing, mismatched, ambiguous, or stale
identity means no selection, Editor query, test, or mutation. Report the
expected and observed identity and obtain fresh read-only evidence; never
choose the first/only candidate. For a proven match, explicitly call
set_active_instancewith its full discoveredName@hash, including in the single-instance case, and verify the response identifies that same ID. - Read back before work. Now read
mcpforunity://project/infothrough the pinned session and compareprojectRootandunityVersionto the same canonical root and complete version. Only then readmcpforunity://editor/state, compilation/import/Play Mode state, or invoke other Editor tools. A selection response alone is not a passing preflight. If readback fails or disagrees, stop without Editor work. - Keep proof current. Record the root, version, full instance ID, session (when exposed), and evidence source in preflight. A reconnect, Editor restart, changed instance list/selection, domain reload, or routing mismatch invalidates the proof: repeat discovery, matching, pinning, and readback before further Editor work. Preserve unsaved scenes and do not auto-switch.
This gate also applies when another workflow invokes MCP indirectly. For pre-Unity-6, successful MCP proof is valid live evidence even if CLI status has no instances. Pinned source inspection can proceed without live proof only for work whose acceptance does not require the Editor; it never authorizes Editor operations on an unproven target. Unity 6+ does not gain automatic legacy-MCP permission from an empty CLI result.
Source schema: instance discovery, project info, and instance selection.
For non-interactive or parsed output, use:
unity <command> --json --non-interactive --no-banner
Apply the repository's approval policy before running commands:
- Read-only discovery (
status,editors,projects,doctor,diagnose,logs,env, barecommand,test_status,recompile_status, and--help) may run without approval. - For a user-requested Unity implementation, repair, or verification task,
focused
unity test,unity command run_tests, recompile checks, shared test batch submissions and publishes, and their status/log/result queries are already authorized after proving the exact project. Do not ask for a separate command approval or accepted task plan. Use a focused filter when practical and preserve unsaved Editor work. Run tests only in the final stage. During development, use the Roslyn compile check, which writes no tracked file and needs no approval. - Other Editor mutations,
run,open,config, and arbitrary Pipeline command execution follow the accepted task scope, declared paths, and risk gates. Do not ask again for each low-risk command within that scope. - Editor/module/package installs or removals, builds, upgrades, auth changes, cloud mutations, project creation, source-control creation/push, and Unity serialized-asset changes require explicit target authorization. The default Pipeline install above is the one standing exception.
build, run, and test can write generated or imported project state. Treat
their project and output paths as declared owned paths, and report the exit code
plus log/report path on failure.
Editor instances and worktrees
Each Unity Editor costs minutes of start-up and import plus several GB of memory, and nothing closes it on its own. Unity locks a project per folder, so worktrees of one repository never block each other. Keep the count low and give every Editor one owner:
-
At most two Editors per repository. Count every Editor open on any checkout or worktree of the repository, whoever opened it. An orchestration owns at most one, in its integration checkout; a single session owns at most one. When the limit is reached, continue code-only work and queue the Editor-bound step. Never open a second Editor on a checkout that already has one. An Editor the user or another live session holds stays theirs.
-
Open through the repository lock. Checking and then opening is a race: two sessions can both see one Editor and both open. Agents never call
unity opendirectly; they run:python "<unity-cli skill dir>/scripts/unity_editor_open.py" --project <project root> --owner <task ID or session>It takes an OS-held lock in the repository's Git common dir, which every worktree shares, and holds it through the Editor count, the open, and the new PID. The OS releases the lock when the script exits, so no lock is ever stale or deleted. It counts Editors from the process table, so it also sees Editors that
unity statuscannot reach (no Pipeline package, below Unity 6). It prints oneEDITOR_OPEN:line:OPENED(0): record the printed PID and checkout.ALREADY_OPEN(3): this checkout has an Editor. Use it when it is yours or you take its task over; otherwise it stays its owner's, so queue.LIMIT_REACHED(4): continue code-only work and queue the Editor-bound step.LOCK_TIMEOUT(5): another open is still running; retry later.OPEN_FAILED(6): nothing was opened, or the Editor is still starting. Checkunity statusand the process list before trying again; never open twice. The script also stops here, instead of guessing, when the process table orgitcannot be read.
--dry-runreports the count under the lock without opening. The running Editors are the slots, so closing an Editor frees its slot. A launch whose Editor has not appeared keeps its slot until the Editor appears; a later open of that project reportsALREADY_OPENwhile it starts. Reservations never expire by age. After a launch that failed (no Editor for the project and nounity openrunning), free its slot with--clear-reservation; the script points this out once a reservation is older than 30 minutes. -
Own what you open. Record the PID and checkout of every Editor you open in the task handoff, or in the session report for untracked work. Close it with
unity close <project>when its Editor-bound work and final-stage tests are done, or at handoff.unity closeexits without saving, so save owned assets first, and leave open (and report) an Editor holding unsaved work you do not own. An owner that takes over a stopped task inherits its recorded Editor: it keeps the integration checkout's Editor and closes any other. -
Never delete
Temp/UnityLockfile. It is Unity's guard against two Editors on one project. If Unity reports the project open, find the process that holds it. -
Code lanes stay Editor-free. Never run
unity open,run,test, orbuildin a lane worktree. Give it what the Roslyn check needs instead:- Seed it from a compiled checkout of the same repository whose Editor is
closed and whose
HEADis the lane's base:unity vcs git worktree add <branch> <source project> --seed full --no-register.--seed cacheis not enough, because generated projects referenceLibrary/PackageCacheby relative path. The CLI skips seeding while the source Editor runs (skip: source-editor-running), so seed all lanes in one pass before the integration Editor opens, or close that Editor briefly (after saving owned assets). - Copy the source project's generated
*.csprojand*.slninto the lane's project root. Seeding copiesLibraryonly.
A lane's
COMPILE_UNVERIFIED(a new assembly, an.asmdefedit) goes to the integration owner, who confirms it with Unity's compile in the integration checkout after applying the lane's diff. Final-stage tests also run there. - Seed it from a compiled checkout of the same repository whose Editor is
closed and whose
Development compile check (Roslyn)
During development, verify each Unity C# change with this check instead of a
Unity Test Runner run. It compiles only the assemblies that contain the changed
files with dotnet build (Roslyn), against the assemblies Unity already
compiled into Library/ScriptAssemblies. It needs no running Editor, so it
also works below Unity 6, and it takes seconds.
python "<unity-cli skill dir>/scripts/unity_compile_check.py" --project <project root> --files <changed and deleted files>
- Add
--dependentsafter changing the public API of an assembly that others reference. It then also compiles every assembly that depends on it. - New files are compiled into the assembly Unity would assign them to, and deleted files are removed, even before Unity regenerates its project files.
- If Unity's compiled copy of a dependency is older than its sources, the check compiles that dependency from source first.
- It ignores
.csprojfiles left over from removed assemblies. - It writes only under the project's
Temp/and one file in the system temp folder. - It needs three things: the .NET SDK, the Unity Editor version the project files target, and one earlier Unity compile of the project on this machine. A code lane gets that compile by seeding, not by opening Unity (see Editor instances and worktrees).
Verdicts:
COMPILE_OK(exit 0): continue.COMPILE_ERRORS(exit 1): lists the errors. Fix them before the next step.COMPILE_UNVERIFIED(exit 2): explains why the check cannot decide, for example a changed.asmdef, missing project files or Editor, or a project Unity never compiled. Fall back to Unity's own compile:recompile_statuswith a live Editor, or MCP for Unity below Unity 6. Or regenerate the project files and run the check again. In a code lane, hand that compile to the integration owner instead.
Test timing:
- Do not run Unity tests during development.
- Write or update the focused EditMode/PlayMode tests, then run them once in the final stage, through the shared test batch: when the implementation is complete, before verifier handoff, commit, or closure.
- After that, re-run only failing tests.
- Reproduce bugs from the supplied evidence (failing-test output, logs, a concrete scenario) instead of re-running tests.
- Run tests earlier only when the user asks.
- Closure gates do not change.
Files in this skill
20unity-cli skill questions
How do I install the unity-cli skill in Claude Code?
Run npx degit furkantokkan/agent-foundry/plugins/agent-foundry/skills/unity-cli ~/.claude/skills/unity-cli. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the unity-cli skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.