🎮 UnitySkills

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.

---

🚀 Core Features

• 🛠️ 729 REST Skills Comprehensive Toolkit: Includes 51 functional source modules plus 19 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.1.0.
• 🔐 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.

---

🔐 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 (Window > UnitySkills > Server) — chat trigger words are no longer supported.

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 in the Server tab if you need per-skill manual gating.

❌ Chat trigger words (e.g. "full auto" / "semi-auto") are no longer recognized. Switch modes in Window > UnitySkills > Server.

📜 Audit log: Library/UnitySkillsAudit.jsonl (per-project, jsonl, auto-rolls at 1MB, keeps 3 files) records every grant / revoke / restricted hit / call. Open Window > UnitySkills > Audit Log 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.

19 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):

---

🏁 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 page

2. Start Server

In Unity, click menu: Window > UnitySkills > Start Server

⏳ 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 > Skill Installer.
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 | 安装指南

---

---

📂 Project Structure

.
├── SkillsForUnity/                 # Unity Editor Plugin (UPM Package)
│   ├── package.json                # com.besty.unity-skills
│   ├── unity-skills~/              # Cross-platform AI Skill Template (tilde-hidden, bundled with package)
│   │   ├── SKILL.md                # Main Skill Definitions (AI-readable)
│   │   ├── scripts/
│   │   │   └── unity_skills.py     # Python Client Library
│   │   ├── skills/                 # 68 module docs (49 REST/module docs + 19 advisory docs)
│   │   └── references/             # Unity Development References
│   └── Editor/Skills/              # Core Skill Logic (51 *Skills.cs files, 729 Skills)
│       ├── SkillsHttpServer.cs     # HTTP Server Core (Producer-Consumer)
│       ├── SkillRouter.cs          # Request Routing & Reflection-based Skill Discovery
│       ├── WorkflowManager.cs      # Persistent Workflow (Task/Session/Snapshot)
│       ├── RegistryService.cs      # Global Registry (Multi-instance Discovery)
│       ├── GameObjectFinder.cs     # Unified GO Finder (name/instanceId/path)
│       ├── BatchExecutor.cs        # Generic Batch Processing Framework
│       ├── GameObjectSkills.cs     # GameObject Operations (18 skills)
│       ├── MaterialSkills.cs       # Material Operations (21 skills)
│       ├── CinemachineSkills.cs    # Cinemachine 2.x/3.x (34 skills)
│       ├── WorkflowSkills.cs       # Workflow Undo/Rollback (23 skills)
│       ├── PerceptionSkills.cs     # Scene Understanding (18 skills)
│       └── ...                     # 729 Skills source code
├── docs/
│   └── SETUP_GUIDE.md              # Complete Setup & Usage Guide
├── CHANGELOG.md                    # Version Update Log
└── LICENSE                         # MIT License

---

⭐Star History

---

📄 License

This project is licensed under the MIT License.

Bundled font (separate license): the editor window bundles a subsetted CJK font SkillsForUnity/Editor/UI/Fonts/UnitySkillsCN-Regular.ttf, derived from Maple Mono (CN variant), licensed under the SIL Open Font License 1.1 — not MIT. The full license and attribution travel with the font in that folder (OFL.txt, THIRD-PARTY-NOTICES.md).