Besty0728/Unity-Skills

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.

Sponsor slots are open. Your logo and link will appear here.
Become a sponsor →

This project is a deep refactoring and feature extension based on the excellent concept of unity-mcp.

• 🛠️ 805 REST Skills Toolkit: 56 source files across 54 categories, plus 28 advisory design modules, with Batch operations.
• ⚡ UnityCLI Support: Bind UnityCLI to cold-start the bound project — no need to launch Unity Hub.
• 🔐 Three-Tier Permission Modes: Approval / Auto / Bypass with dual approval channels, aligned with Claude Code permission modes.
• 🤖 6 Major IDEs Native Support: Claude Code / Antigravity / Codex / Cursor / OpenCode / Kimi Code — one-click install and use.
• 🛡️ Transactional Atomicity: Failed operations auto-rollback, leaving scenes clean.
• 🌍 Multi-Instance Control: Automatic port discovery and global registry for controlling multiple Unity projects at once.
• 🔗 Stable Long Connections: Configurable request timeout (default 15 minutes), automatic recovery after Domain Reload.
• 🛡️ Anti-Hallucination Guardrails: Each Skill module includes DO NOT lists and routing rules.

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 rehearsal — returns parameter validation and an impact estimate, writes nothing.
• At execution: the server derives high-risk gating (NeverInSemi) from each skill's risk metadata — gating never depends on the AI behaving well; Allowlist grants a persistent per-skill pass.
• After execution: every call, grant, revoke and blocked hit lands in a JSONL audit trail, browsable in the panel; deletions are audited too.
• After a mistake: five types of persistent snapshots survive Domain Reloads; workflow_undo_task rolls back one task, not the whole project; POST /skills/batch runs as a transaction (cross-step $ref, rollback on failure, ?diff=1 net change).

Full mechanics → Operating Modes & Governance

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.

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 → ⚙ Settings → Server section (chat trigger words are no longer supported).

Upgrading users are detected automatically and stay on Bypass, preserving the previous Full-Auto behavior with no action required. Dual approval channels (Dialog / Panel), the audit log (Library/UnitySkillsAudit.jsonl), Allowlist and installer details → Operating Modes & Governance.

28 advisory design modules (architecture, performance, design patterns, testability, package-specific source rules, etc.) are available in all modes and loaded on demand.

This project has been deeply optimized for the following environments (tools not listed are not necessarily unsupported — they just lack a quick installer; use Custom Installation instead. Per-tool skill directories are listed in the Manual Installation section below):

Overview: Install Unity Plugin → Start UnitySkills Server → AI Uses Skills

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

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.

1. Open Window > UnitySkills and go to the AI Config tab.
2. Select the corresponding terminal icon and click "Install" — the installer copies the unity-skills~/ template from the package to the target location, no manual copying needed.

🔄 Auto-sync on update: after you upgrade the package, tools you already installed are refreshed to the new version automatically (nothing new is ever installed for you); turn it off in ⚙ Settings ▸ AI Tools.

Codex Note: Antigravity and Codex share .agents/skills/ in workspace mode — installing once makes the skill available to both; no AGENTS.md declaration needed for Codex.

📘 For complete installation and usage instructions, see: Setup Guide | 安装指南

.
├── 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/                 # 82 module docs (54 REST/module docs + 28 documentation-only docs)
│   │   └── references/             # Unity Development References
│   └── Editor/
│       ├── Locales/                # Decoupled JSON Localization Assets (en.json, zh-CN.json, ru.json)
│       ├── Skills/                 # Core Skill Logic (56 *Skills.cs files → 54 SkillCategory categories, 805 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
│       │   ├── Localization.cs     # Multi-Language Localization Engine
│       │   └── ...                 # 805 Skills source code
│       └── UI/                     # UI Toolkit Windows & Controllers
│           ├── UnitySkillsWindow.{cs,uxml,uss} # Main Dashboard Window
│           ├── UnityCliWindow.{cs,uxml,uss}    # Unity CLI Configuration Panel
│           ├── AuditLogWindow.{uxml,uss}       # Audit Log Viewer
│           ├── Controllers/                    # UI Tab & Widget Controllers
│           └── Tabs/                           # UXML Tab Layouts & Settings Drawer
├── docs/
│   └── SETUP_GUIDE.md              # Complete Setup & Usage Guide
├── CHANGELOG.md                    # Version Update Log
└── LICENSE                         # MIT 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).