REST API-based AI-driven Unity Editor Automation Engine Let AI control Unity scenes directly through Skills
๐ We are now indexed by DeepWiki!
Got questions? Check out the AI-generated docs โ
> The current official maintenance baseline is **Unity 2022.3+**. Some Unity 2021 compatibility logic may still remain in the codebase, but future feature work, regression testing, and adaptation will focus on **2022.3+ / Unity 6**.
## ๐ค Acknowledgments
This project is a deep refactoring and feature extension based on the excellent concept of [unity-mcp](https://github.com/CoplayDev/unity-mcp).
---
## ๐ Core Features
- ๐ ๏ธ **776 REST Skills Comprehensive Toolkit**: Includes 54 functional source modules plus 24 advisory design modules, with Batch operations for multi-object control.
- โก **Revolutionary Efficiency Boost (v2.0.1+)**: Schema caching + exponential backoff polling + BATCH-FIRST guidance โ **Token consumption โ 96%**, **simple tasks 4-6 calls โ 1 call (โ 75-83%)**. Current: v2.4.1.
- ๐ **Three-Tier Permission Modes (v1.9.0+)**: Approval / Auto / Bypass with dual approval channels (Dialog / Panel), aligned with Claude Code permission modes; zero-impact upgrade for existing users.
- ๐ค **4 Major IDEs Native Support**: Claude Code / Antigravity / Codex / Cursor โ one-click install and use.
- ๐ก๏ธ **Transactional Atomicity**: Failed operations auto-rollback, leaving scenes clean and safe.
- ๐ **Multi-Instance Simultaneous Control**: Automatic port discovery and global registry for controlling multiple Unity projects at once.
- ๐ **Ultra-Stable Long Connections**: Configurable request timeout (default 15 minutes), automatic recovery after Domain Reload, with retry hints during script compilation/asset updates.
- ๐ก๏ธ **Anti-Hallucination Guardrails**: Each Skill module includes DO NOT lists and routing rules to prevent calls to nonexistent commands or parameter errors.
---
## ๐ก๏ธ Built for Trust: The Governance Layer
An AI driving the Editor writes to real scenes, prefabs and `.meta` files. The interesting question isn't whether it *can* โ it's what happens when it gets something wrong. UnitySkills answers that at four points in the call lifecycle.
- **Before execution โ `?mode=dryRun` / `?mode=plan`**: `POST /skill/{name}?mode=dryRun` writes nothing and returns parameter validation (`missingParams` / `unknownParams` / `typeErrors` / `semanticErrors` / `warnings`) plus an impact estimate (`mutatesScene` / `mutatesAssets` / `mayTriggerReload` / `mayEnterPlayMode` / `riskLevel`). Skills with a semantic planner also return `steps` / `changes`.
- **At execution โ per-operation risk gating**: every skill declares `RiskLevel` / `Operation` / `MayEnterPlayMode` / `MayTriggerReload` in its `[UnitySkill]` metadata, and the server derives NeverInSemi from that metadata โ gating never depends on the AI behaving well. **Allowlist** grants a persistent pass to individual skills; the optional `ConfirmationToken` handshake (off by default โ โ Settings โ Runtime โ Require Confirmation) adds one more gate on high-risk skills.
- **After execution โ JSONL audit trail**: every call, grant, revoke and blocked hit is appended to `Library/UnitySkillsAudit.jsonl` (1 MB rotation, primary + 3 historical files), browsable and filterable in the panel. Deleting audit entries is itself recorded, as `audit_deleted` / `audit_cleared`.
- **After a mistake โ typed, persistent snapshot rollback**: Workflow snapshots are typed (`Modified` / `Created` / `Deleted` / `Moved` / `Setting`), and the asset file and its `.meta` are content-addressed independently (`fileHash` / `metaFileHash`) under `Library/UnitySkills/`, so history survives Domain Reloads and editor restarts. `workflow_undo_task` rolls back one task, not the whole project.
- **Batch as a transaction**: `POST /skills/batch` supports fail-fast or `continueOnError`, cross-step `$ref` to reuse an earlier step's output, rollback on failure, and `?diff=1` for the aggregated net change.
### How this compares
| Dimension | UnitySkills | Typical MCP bridge | Unity's official AI Assistant |
| :--- | :--- | :--- | :--- |
| **Permission granularity** | Per-operation: three modes (Approval / Auto / Bypass) + risk metadata on every skill + per-skill Allowlist | No permission model โ once connected, the whole tool surface is callable | Per-client trust (Pending Connections โ Allow / Revoke); after approval, calls are not distinguished by operation |
| **Audit** | Structured JSONL for every call / grant / revoke / block, browsable in-panel; deletions are audited too | Process logs only; no structured per-call record | Surfaced as chat history and checkpoints rather than a per-operation audit record |
| **Rollback granularity** | Per-task, five snapshot types, file and `.meta` content-addressed, persists across sessions | Relies on Unity's native Undo stack; not guaranteed to survive a Domain Reload | Project-wide checkpoints taken per prompt โ restoring rewinds the entire project to that point |
| **Pre-execution preview** | `?mode=dryRun` / `?mode=plan` โ semantic parameter validation + impact estimate, nothing written | No equivalent found | No pre-execution parameter validation or impact preview found |
| **Batch transactions** | `POST /skills/batch` โ fail-fast / `continueOnError`, cross-step `$ref`, rollback, `?diff=1` net change | Per-call tool invocations, no transaction semantics | Not exposed as a batch transaction |
> The **UnitySkills** column describes mechanisms that exist in this repository and can be checked against the source or by calling the endpoints. The other two columns reflect **public material and open-source repositories surveyed in 2026-07**; they characterise a class of tooling rather than any specific project, and those capabilities may have changed since.
---
## ๐ Operating Modes (v1.9.0+)
UnitySkills ships with a true server-side permission system aligned with Claude Code permission modes. All mode switching happens in the Unity panel โ open **Window > UnitySkills**, click the โ (Settings) button, and use the **Server** section โ chat trigger words are no longer supported.
| Mode | Default | Behavior | Use Case |
|:-----|:-------:|:---------|:---------|
| **Approval** | โ | AI must request โ user approves โ execute (returns `MODE_RESTRICTED` + grant token) | Manual control, sensitive projects |
| **Auto** | New installs | AI runs FullAuto skills directly; server only blocks auto-detected high-risk ops (NeverInSemi) | Day-to-day development |
| **Bypass** | Existing installs (upgrade) | All skills run unrestricted; only `ConfirmationToken` gate remains for high-risk ops | Automation, CI, fast iteration |
**Two approval channels under Approval mode**:
- **Dialog** (default) โ AI explains intent + grant token, user agrees in chat, AI replays the token via `POST /permission/grant`
- **Panel** (opt-in) โ grant token only takes effect after user clicks **[Approve]** in the Unity panel; AI-issued grants without panel approval return `GRANT_PENDING_APPROVAL`
**Zero-impact upgrade for existing users**: the plugin detects legacy `UnitySkills_*` EditorPrefs keys and keeps **Bypass** as the default, preserving the previous Full-Auto behavior with no action required. New installations default to **Auto** โ FullAuto skills run directly, only NeverInSemi (Delete / MayEnterPlayMode / MayTriggerReload / high-risk) operations are blocked. Switch to **Approval** from the โ Settings drawer's Server section if you need per-skill manual gating.
> โ Chat trigger words (e.g. `"full auto"` / `"semi-auto"`) are no longer recognized. Switch modes via the โ Settings button in **Window > UnitySkills**.
>
> ๐ Audit log: `Library/UnitySkillsAudit.jsonl` (per-project, jsonl, auto-rolls at 1MB, keeps 3 files) records every grant / revoke / restricted hit / call. Open it from the โ Settings drawer โ **View Audit Log** (or press Alt+Shift+L) to browse, filter, delete individual entries (โ), or wipe everything (๐ Clear All) โ deletions themselves are appended as `audit_deleted` / `audit_cleared` events so the log stays auditable.
>
> ๐ The Skill Installer card shows a **per-scope uninstall** button that auto-adapts: disabled when nothing's installed, a single button labeled with its scope when only one is installed, and a dropdown (`Uninstall โพ`) listing Project / Global when both are installed.
>
> 24 advisory design modules (architecture, performance, design patterns, testability, package-specific source rules, etc.) are available in all modes and loaded on demand.
---
## ๐๏ธ Quick Install Supported IDE/Terminals
This project has been deeply optimized for the following environments to ensure a continuous and stable development experience (tools not listed below are not necessarily unsupported โ they just lack a quick installer; use ***Custom Installation*** to the corresponding directory):
| AI Terminal | Support Status | Special Features |
| :--- | :---: | :--- |
| **Antigravity** | โ Supported | Open Agent Skills standard via `.agents/skills/` (workspace) and `~/.gemini/antigravity/skills/` (global). |
| **Claude Code** | โ Supported | Intelligent Skill intent recognition, supports complex multi-step automation. |
| **Codex** | โ Supported | Supports `$skill` explicit invocation and implicit intent recognition. Shares `.agents/skills/` with Antigravity in workspace mode. |
| **Cursor** | โ Supported | Auto-discovers `.cursor/skills/` and `.agents/skills/`; supports `/skill-name` explicit invocation; visible in Settings โ Rules. |
---
## ๐ Quick Start
> **Overview**: Install Unity Plugin โ Start UnitySkills Server โ AI Uses Skills
### 1. Install Unity Plugin
Add via Unity Package Manager using Git URL:
**Stable Version (main)**:
```
https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity
```
**Beta Version (beta)**:
```
https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity#beta
```
**Specific Version** (e.g., v1.6.0):
```
https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity#v1.6.0
```
> ๐ฆ All version packages are available on the [Releases](https://github.com/Besty0728/Unity-Skills/releases) page
### 2. Open the Panel & Start Server
In Unity, open menu: `Window > UnitySkills` (or press Alt+Shift+U). Use the server toggle switch in the top bar to start it; once started it auto-restarts across domain reloads.
> โณ `script_*`, `debug_force_recompile`, `debug_set_defines`, some asset reimports, and package changes may trigger compilation or Domain Reload. Temporary REST unavailability during that window is expected; wait a moment and retry.
### 3. One-Click AI Skills Configuration
1. Open `Window > UnitySkills` and go to the **AI Config** tab.
2. Select the corresponding terminal icon (Claude / Antigravity / Codex / Cursor).
3. Click **"Install"** to complete the environment configuration without manual code copying.
> The installer copies the `unity-skills~/` template directory from the package to the target location.
>
> Installer output files (generated in target directory):
> - `SKILL.md`
> - `skills/`
> - `references/`
> - `scripts/unity_skills.py`
> - `scripts/agent_config.json` (contains Agent identifier)
> **Codex Note**: Antigravity and Codex share `.agents/skills/` in workspace mode โ installing once for either makes the skill available to both. Codex auto-discovers skills in `.agents/skills/`; no `AGENTS.md` declaration needed.
๐ For complete installation and usage instructions, see: [Setup Guide](https://github.com/besty0728/unity-skills/blob/HEAD/docs/SETUP_GUIDE.md) | [ๅฎ่ฃ ๆๅ](https://github.com/besty0728/unity-skills/blob/HEAD/docs/SETUP_GUIDE_CN.md)
4. Manual Skills Installation (Optional)
If one-click installation is not supported or preferred, follow this **standard procedure** for manual deployment (applicable to all tools supporting Skills):
#### โ Standard Installation Method A
1. **Custom Installation**: In the installation interface, select the "Custom Path" option to install Skills to any directory you specify (e.g., `Assets/MyTools/AI`) for easier project management.
#### โ Standard Installation Method B
1. **Locate Skills Source Directory**: The `SkillsForUnity/unity-skills~/` directory in the UPM package is the distributable Skills template (root directory contains `SKILL.md`).
2. **Find the Tool's Skills Root Directory**: Different tools have different paths; refer to the tool's documentation first.
3. **Copy Completely**: Copy the entire contents of `unity-skills~/` to the tool's Skills root directory (rename to `unity-skills/`).
4. **Create agent_config.json**: Create an `agent_config.json` file in the `unity-skills/scripts/` directory:
```json
{"agentId": "your-agent-name", "installedAt": "2026-02-11T00:00:00Z"}
```
Replace `your-agent-name` with the name of your AI tool (e.g., `claude-code`, `antigravity`, `codex`, `cursor`).
5. **Directory Structure Requirements**: After copying, maintain the structure as follows (example):
- `unity-skills/SKILL.md`
- `unity-skills/skills/`
- `unity-skills/references/`
- `unity-skills/scripts/unity_skills.py`
- `unity-skills/scripts/agent_config.json`
6. **Restart the Tool**: Let the tool reload the Skills list.
7. **Verify Loading**: Trigger the Skills list/command in the tool (or execute a simple skill call) to confirm availability.
#### ๐ Common Tool Directory Reference
The following are verified default directories (if the tool has a custom path configured, use that instead):
- Claude Code: `~/.claude/skills/`
- Antigravity: `~/.gemini/antigravity/skills/` (global) or `.agents/skills/` (workspace)
- OpenAI Codex: `~/.agents/skills/` (global) or `.agents/skills/` (workspace, shared with Antigravity)
- Cursor: `~/.cursor/skills/` (global) or `.cursor/skills/` (workspace); also auto-discovers `.agents/skills/`
#### ๐งฉ Other Tools Supporting Skills
If you're using other tools that support Skills, install according to the Skills root directory specified in that tool's documentation. As long as the **standard installation specification** is met (root directory contains `SKILL.md` and maintains `skills/`, `references/`, and `scripts/` structure), it will be correctly recognized.
---
