Skip to content
Skills Library
Programming · Automation

unity-development

/unity-development

Use for Unity Editor automation through UniCli in projects where `unicli` is available: running `unicli exec`/`unicli eval`, editing files under `Assets/` or `Packages/`, compiling Unity code, running EditMode/PlayMode tests, and creating or modifying GameObjects, scenes, prefabs, assets, packages, build settings, project settings, or memory snapshots. Follow required safeguards such as `AssetDatabase.Import` after file changes and `Compile` verification after C# edits.

Repository
UniCli ↗
Licence
MIT
Last repository change
04.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 04.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use for Unity Editor automation through UniCli in projects where `unicli` is available: running `unicli exec`/`unicli eval`, editing files under `Assets/` or `Packages/`, compiling Unity code, running EditMode/PlayMode tests, and creating or modifying GameObjects, scenes, prefabs, assets, packages, build settings, project settings, or memory snapshots. Follow required safeguards such as `AssetDatabase.Import` after file changes and `Compile` verification after C# edits.

Original author description

Use for Unity Editor automation through UniCli in projects where `unicli` is available: running `unicli exec`/`unicli eval`, editing files under `Assets/` or `Packages/`, compiling Unity code, running EditMode/PlayMode tests, and creating or modifying GameObjects, scenes, prefabs, assets, packages, build settings, project settings, or memory snapshots. Follow required safeguards such as `AssetDatabase.Import` after file changes and `Compile` verification after C# edits.

How it works

  1. RULES — Always Follow These
  2. Project Path
  3. Prerequisites
  4. Executing Commands
  5. Key Workflows
  6. Running Custom Code
  7. Custom Command Handlers
  8. Tips
Original SKILL.md headings · 269 lines, 1,752 words
SKILL.md preview
---
name: unity-development
description: >-
  Use for Unity Editor automation through UniCli in projects where `unicli` is
  available: running `unicli exec`/`unicli eval`, editing files under `Assets/`
  or `Packages/`, compiling Unity code, running EditMode/PlayMode tests, and
  creating or modifying GameObjects, scenes, prefabs, assets, packages, build
  settings, project settings, or memory snapshots. Follow required safeguards such as
  `AssetDatabase.Import` after file changes and `Compile` verification after C#
  edits.
metadata:
  version: "1.6.0"
---

# UniCli — Unity Editor CLI

UniCli lets you interact with Unity Editor directly from the terminal.
The CLI (`unicli`) communicates with the Unity Editor over named pipes, so the Editor must be open with the `com.yucchiy.unicli-server` package installed.

## RULES — Always Follow These

1. **After creating/modifying ANY file under `Assets/` or `Packages/`**: Run `unicli exec AssetDatabase.Import --path "<path>" --json` to generate `.meta` files. **Never create `.meta` files manually** — always let Unity generate them via this command. Unity requires `.meta` files for every asset — skipping this causes missing references, broken imports, and compilation errors. This applies to all file types: `.cs`, `.asmdef`, `.asset`, `.prefab`, directories, etc.
2. **After modifying C# code in the Unity project**: Run `unicli exec Compile --json` to verify compilation.
3. **Always use `--json`** when parsing output programmatically.
4. **If connection to Unity Editor fails**: Retry 2–3 times, then ask the user to confirm Unity Editor is running with the project open.
5. **For platform-specific verification**: Use `unicli exec BuildPlayer.Compile --target <platform> --json` to catch platform-specific errors (missing `#if` guards, unsupported APIs, etc.).
6. **When running tests**: Always use the default `--resultFilter failures` (or `--resultFilter none` for summary-only) to keep output minimal. Only use `--resultFilter all` when you specifically need to inspect individual passed test details. This prevents large test suites from flooding context. Stack traces are omitted by default (`--stackTraceLines 0`); use `--stackTraceLines 3` when you need to diagnose a failure location.
7. **When checking console logs**: Use `Console.GetLog` with `{"logType":"Warning,Error"}` to filter out informational noise and focus on actionable issues. Stack traces are omitted by default; use `{"logType":"Error","stackTraceLines":3}` when debugging errors.
8. **Discover commands dynamically**: Use `unicli commands --json` to list all available commands and `unicli exec <command> --help` to see parameters for any command. `--help` includes nested type details when applicable, and `commands --json` provides nested schemas via each command's `requestTypeDetails` and `responseTypeDetails`. Match nested type details by `typeId`; `type` and `typeName` are display labels and may not be unique. Do not rely on memorized command lists — the project may have custom commands.
9. **Before scene-affecting operations**: Run `unicli exec Editor.Status` (without `--json` — the compact text summary is enough to check for dirty state and keeps output small) before `TestRunner.RunPlayMode`, `BuildPlayer.Build`, `Scene.Open`, `Scene.New`, `Scene.Close`, `Menu.Execute`, or entering Play Mode. `TestRunner.RunPlayMode` is the most common offender: the test runner creates a temporary test scene and swaps out the currently open scenes, so any unsaved scene changes at that moment can trigger a save prompt, abort the run, or leave the CLI waiting forever. If dirty scenes came from your own edits, save only the changes that should persist; revert or discard temporary probe changes when that is safer. If the dirty state may be from the user, do not save or discard it; ask the user how to proceed.
10. **When commands hang or time out**: Suspect a Unity Editor modal dialog such as a scene save prompt. Do not keep retrying blindly; ask the user to close or resolve the dialog, then retry.

## Project Path

By default, `unicli` looks for a Unity project in the current working directory.
If the Unity project is in a subdirectory, set the `UNICLI_PROJECT` environment variable:

```bash
export UNICLI_PROJECT=path/to/unity/project
unicli exec Compile --json
```

Or prefix each command:

```bash
UNICLI_PROJECT=path/to/unity/project unicli exec Compile --json
```

## Prerequisites

Before running commands, verify that the CLI is installed and the Editor is reachable:

```bash
unicli check
```

If `unicli check` reports that the server package is not installed, run `unicli install` to install it:

```bash
unicli install
```

If the server package version does not match the CLI version, run `unicli install --update` to update it:

```bash
unicli install --update
```

If the package is installed but the connection fails, make sure Unity Editor is open with the target project loaded. Retry a few times — the Editor may need a moment to start the server.

## Executing Commands

Run commands with `unicli exec <command>`. Pass parameters as `--key value` flags or raw JSON. Use JSON for arrays and nested values:

```bash
unicli exec GameObject.Find '{"name":"Main Camera"}' --json
```

Boolean flags can be passed without a value:

```bash
unicli exec GameObject.Find --includeInactive --json
```

Array parameters can be passed by repeating the same flag:

```bash
unicli exec BuildPlayer.Build --locationPathName "Builds/Test.app" --options Development --options ConnectWithProfiler --json
```

### Common options

- `--json` — Output in JSON format (recommended for structured processing)
- `--timeout <ms>` — Set command timeout in milliseconds
- `--no-focus` — Don't bring Unity Editor to front
- `--help` — Show command parameters and nested type details

## Key Workflows

**Pre-flight before scene-affecting commands:**

```bash
unicli exec Editor.Status
# Save only when the dirty scenes are your own intended persistent changes.
unicli exec Scene.Save '{"all":true}' --json
unicli exec TestRunner.RunPlayMode --json
```

**Compile and run tests:**

```bash
unicli exec Compile --json
unicli exec TestRunner.RunEditMode --json
unicli exec TestRunner.RunPlayMode --json
```

**Capture SceneView screenshots (works in Edit Mode, no Play Mode required):**

```bash
# 2D mode (orthographic, facing the XY plane); lookAt is a GameObject path, offset shifts the capture center
unicli exec Scene.Screenshot2D '{"lookAt":"Player","offset":[1,0],"size":5,"path":"Screenshots/map.png"}' --json
# 3D mode: orbit the lookAt point by yaw/pitch at the given distance
unicli exec Scene.Screenshot3D '{"lookAt":"Player","yaw":45,"pitch":30,"distance":10,"path":"Screenshots/shot.png"}' --json
```

**Inspect and modify settings:**

```bash
unicli exec PlayerSettings.Inspect --json
unicli eval 'PlayerSettings.companyName = "MyCompany";' --json
```

**Dynamic C# code execution (Eval):**

`unicli eval` compiles and executes arbitrary C# code in the Unity Editor context. Use shell heredocs for multi-line code:

```bash
unicli eval 'return Application.unityVersion;' --json

unicli eval "$(cat <<'EOF'
var go = GameObject.Find("Main Camera");
return go.transform.position;
EOF
)" --json
```

Options:
- `--declarations '<code>'` — Additional type declarations (classes, structs, enums) included outside the Execute method
- The generated eval code receives a `cancellationToken` variable for cooperative cancellation with `async`/`await`

## Running Custom Code

When built-in commands don't cover what you need, choose the right approach:

1. **One-shot tasks → Eval**: Use `unicli eval` for ad-hoc operations, quick inspections, prototyping, and tasks that don't need to be reused. No files to create or compile — just pass the code directly.
2. **Reusable project commands → CommandHandler**: Use `CommandHandler` when the operation will be called repeatedly or is part of the project's workflow. This provides type-safe parameters, structured responses, and discoverability via `unicli commands`.

**Connect to a running player:**

`Connection.*` commands manage the Unity Editor's PlayerConnection — used to connect to Development Builds running on devices or the local machine. This connection is required for remote debug commands and profiler data collection.

```bash
unicli exec Connection.List --json                          # List available targets
unicli exec Connection.Connect '{"id":-1}' --json           # Connect by player ID
unicli exec Connection.Connect '{"ip":"192.168.1.100"}' --json  # Connect by IP
unicli exec Connection.Connect '{"deviceId":"SERIAL"}' --json   # Connect by device serial
unicli exec Connection.Status --json                        # Check connection status
```

**Invoke remote debug commands on connected player:**

`Remote.*` commands invoke debug commands on a connected Development Build. Requires: `UNICLI_REMOTE` scripting define symbol + Development Build with Autoconnect Profiler enabled.

```bash
unicli exec Remote.List --json
unicli exec Remote.Invoke '{"command":"Debug.Stats"}' --json
unicli exec Remote.Invoke '{"command":"Debug.GetPlayerPref","data":"{\"key\":\"HighScore\",\"type\":\"int\"}"}' --json
```

Built-in debug commands: `Debug.SystemInfo`, `Debug.Stats`, `Debug.GetLogs`, `Debug.GetHierarchy`, `Debug.FindGameObjects`, `Debug.GetScenes`, `Debug.GetPlayerPref`

**Investigate a memory leak:**

`MemorySnapshot.*` commands are available when the project has `com.unity.memoryprofiler`. Captures can come from `MemorySnapshot.Capture`, `Profiler.TakeSnapshot`, or the Memory Profiler window; commands read `.snap` paths or named loaded snapshots and keep heavy snapshot data out of the CLI response.

```bash
unicli exec MemorySnapshot.Capture '{"path":"MemoryCaptures/before.snap"}' --json
# Reproduce the suspected leak in Play Mode or a connected player.
unicli exec MemorySnapshot.Capture '{"path":"MemoryCaptures/after.snap"}' --json
unicli exec MemorySnapshot.Load '{"path":"MemoryCaptures/before.snap","name":"before"}' --json
unicli exec MemorySnapshot.Load '{"path":"MemoryCaptures/after.snap","name":"after"}' --json
unicli exec MemorySnapshot.AllOfMemory '{"snapshot":"after","baseSnapshot":"before","limit":20,"minSize":1048576,"minSizeDelta":1048576}' --json
unicli exec MemorySnapshot.AllOfMemory '{"snapshot":"after","includeBreakdownTree":true,"pathFilter":"Native/Unity Subsystems","pathDepth":1,"memoryMetric":"both"}' --json
unicli exec MemorySnapshot.Diff '{"baseSnapshot":"before","targetSnapshot":"after","scope":"native","minSizeDelta":1048576}' --json
unicli exec MemorySnapshot.TopObjects '{"snapshot":"after","typeFilter":"Texture2D","limit":20}' --json
unicli exec MemorySnapshot.TopObjects '{"snapshot":"after","scope":"managed","groupByType":true,"limit":20}' --json
unicli exec MemorySnapshot.Analyze '{"snapshot":"after","baseSnapshot":"before","limit":10}' --json
```

Useful MemorySnapshot commands:

- `MemorySnapshot.Capture` — capture a `.snap` file; optional `flags` are `Unity.Profiling.Memory.CaptureFlags` names.
- `MemorySnapshot.List` / `MemorySnapshot.Load` — list files, then pin a snapshot under a stable `name`/`id`.
- `MemorySnapshot.Status` / `MemorySnapshot.Unload` — inspect loaded/cached analyses, release one by id/name, or clear all cached entries.
- `MemorySnapshot.Summary` — category totals and metadata; use `snapshot` or `path`, omitted `path` uses the latest `MemoryCaptures/*.snap`.
- `MemorySnapshot.AllOfMemory` — Memory Profiler All Of Memory style report; default is bounded type sections. Use `includeBreakdownTree`/`pathFilter`/`pathDepth` for All Of Memory tree paths, and `memoryMetric` (`allocated`, `resident`, `both`) for tree sorting and `minSize`; type/object sections remain allocated-based.
- `MemorySnapshot.TopObjects` — largest native objects or native/managed type totals; use `scope:"managed"` for managed type aggregation.
- `MemorySnapshot.Diff` — native/managed type deltas; use `baseSnapshot`/`targetSnapshot` or paths, omitted paths use latest and second latest snapshots.
- `MemorySnapshot.Analyze` — compact one-shot report combining summary, top types/objects, and optional diff.

## Custom Command Handlers

The server auto-discovers all `ICommandHandler` implementations via `TypeCache`, so no manual registration is required.

Place custom handlers under `Assets/Editor/UniCli/` with a dedicated asmdef:

```bash
# 1. Create asmdef and add reference to UniCli.Server.Editor
unicli exec AssemblyDefinition.Create --path "Assets/Editor/UniCli/MyProject.UniCli.Editor.asmdef" --name "MyProject.UniCli.Editor" --editorOnly --json
unicli exec AssemblyDefinition.AddReference --path "Assets/Editor/UniCli/MyProject.UniCli.Editor.asmdef" --reference "UniCli.Server.Editor" --json

# 2. Create handler script, then import and compile
unicli exec AssetDatabase.Import --path "Assets/Editor/UniCli" --json
unicli exec Compile --json

# 3. Verify registration and execute
unicli commands --json
unicli exec MyCategory.MyAction --targetName "test" --json
```

### Handler implementation

```csharp
using System.Threading;
using System.Threading.Tasks;
using UniCli.Protocol;
using UniCli.Server.Editor.Handlers;

namespace MyProject.UniCli.Editor.Handlers
{
    [System.Serializable]
    public class MyRequest
    {
        public string targetName = "";
    }

    [System.Serializable]
    public class MyResponse
    {
        public string result;
    }

    public sealed class MyCustomHandler : CommandHandler<MyRequest, MyResponse>
    {
        public override string CommandName => "MyCategory.MyAction";
        public override string Description => "Description shown in unicli commands";

        protected override ValueTask<MyResponse> ExecuteAsync(MyRequest request, CancellationToken cancellationToken)
        {
            return new ValueTask<MyResponse>(new MyResponse
            {
                result = $"Processed {request.targetName}"
            });
        }
    }
}
```

Key rules:
- Request/Response types must be `[Serializable]` with **public fields** (not properties) — required by `JsonUtility`
- Use `Unit` as `TRequest` when no input is needed, or as `TResponse` when no output is needed
- Throw `CommandFailedException` with response data on failure
- For async operations, use `TaskCompletionSource` + `await` with `WithCancellation(cancellationToken)` to wait for Unity callbacks
- Constructor parameters are resolved from `ServiceRegistry` for dependency injection

## Tips

- Run `unicli commands --json` to discover all available commands, including project-specific custom commands.
- Run `unicli exec <command> --help` to see parameters, types, defaults, and nested type details for any command.
- Run `unicli commands --json` to get machine-readable schemas; nested types are represented by each command's `requestTypeDetails` and `responseTypeDetails`, and `typeId` is the stable key for matching them.
- If a command times out, increase the timeout: `unicli exec Compile --timeout 60000`.
Files in this package (2)
  • SKILL.md 15 KB
  • agents/openai.yaml 1 KB

Versions

RepositoryScoreLicence
This page · yucchiy/UniCli100MIT
yucchiy/UniCli100MIT
data-oriented-design-for-games/unity-data-oriented-design-skills100MIT
hermeticormus/claude-code-game-development95MIT

Database snapshot: 13.11.2026 · package version b82d129e860e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100unity-tests-write
    Use when writing Unity tests, including EditMode tests, PlayMode tests, performance testing, and code coverage
  • 95unity-mcp-skill
    Orchestrate Unity Editor via MCP (Model Context Protocol) tools and resources. Use when working with Unity projects through MCP for Unity - creating/modifying GameObjects, editing scripts, managing scenes, running tests, or any Unity Editor automation. Provides best practices,…
  • 85unity-skills
    Automate the Unity Editor through a local REST API — scripts, scenes, prefabs, assets, materials, lighting, tests and hundreds of other Editor operations. Use when the user wants to actually operate the Unity Editor from chat — create, modify or batch-edit…
  • 88unity-batchmode
    Runs Unity without the editor UI - EditMode and PlayMode tests, player builds through a build script with a proper exit code, and compile checks - and reads the Unity log to report errors. Use when the user wants to build a Unity game from the terminal or CI, run Unity Test…
  • 95unity-mcp-orchestrator
    Orchestrate Unity Editor via MCP (Model Context Protocol) tools and resources. Use when working with Unity projects through MCP for Unity - creating/modifying GameObjects, editing scripts, managing scenes, running tests, or any Unity Editor automation. Provides best practices,…
  • 90unity-verification
    Unity verification rules. Use when checking that a Unity change compiles or works, running Unity tests, building a player, running C# in the Editor, classifying Unity involvement for issue triage or selection, or when Unity cannot run here or the editor is locked.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.