unity-mcp-skill

# 🎮 UnitySkills <p align="center"> <img src="https://img.shields.io/badge/Unity-2021.3%2B-black?style=for-the-badge&logo=unity" alt="Unity"> <img src="https://img.shields.io/badge/Skills-431-green?style=for-the-badge" alt="Skills"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-orange?style=for-the-badge" alt="License"></a> <a href="README_EN.md"><img src="https://img.shields.io/badge/README-English-blue?style=for-the-badge" alt="English"></a> </p> <p align="center"> <b>AI-Powered Unity Editor Automation Engine Based on REST API</b><br> <i>Let AI Directly Control Unity Scenes via Skills</i> </p> <p align="center"> 🎉 We have been included in <b>DeepWiki</b>!<br> Have questions? Consult the AI-generated project documentation → <a href="https://deepwiki.com/Besty0728/Unity-Skills"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a> </p> ## 🤝 Acknowledgements This project is a deep refactoring and functional extension based on the excellent concept of [unity-mcp](https://github.com/CoplayDev/unity-mcp). --- ## 🚀 Core Features - ⚡ **Extreme Efficiency**: Supports **Result Truncation** and **SKILL.md** slimming to maximize token savings. - 🛠️ **Versatile Toolkit**: Built-in 431 Skills, supports **Batch** operations, greatly reducing HTTP communication overhead and significantly improving execution efficiency. - 🛡️ **Security First**: Supports **Transactional** atomicity, automatic rollback on operation failure, and zero residual scenes. - 🌍 **Multi-Instance Support**: Automatic port discovery, global registry, supports controlling multiple Unity projects simultaneously. - 🤖 **Deep Integration**: Exclusive support for **Antigravity Slash Commands**, unlocking a new `/unity-skills` interactive experience. - 🔌 **Full Environment Compatibility**: Perfectly supports mainstream AI terminals such as Claude Code, Antigravity, and Gemini CLI. - 🎥 **Cinemachine 2.x/3.x Dual Version Support**: Automatically detects the Unity version and installs the corresponding Cinemachine, supporting advanced camera controls such as **MixingCamera**, **ClearShot**, **TargetGroup**, and **Spline**. - 🔗 **Stable Connection for Ultra-Long Tasks**: Request timeout is user-configurable (default 60 minutes), automatically resumes on the same port after Domain Reload, and the Python client automatically synchronizes timeout configurations, completely solving the problem of disconnection during long tasks. --- ## 🏗️ Supported IDEs / Terminals This project has been deeply optimized for the following environments to ensure a continuous and stable development experience: | AI Terminal | Support Status | Featured Functions | | :--- | :---: | :--- | | **Antigravity** | ✅ Perfect Support | Supports `/unity-skills` slash commands, natively integrated workflow. | | **Claude Code** | ✅ Perfect Support | Intelligently recognizes Skill intent, supports complex multi-step automation. | | **Gemini CLI** | ✅ Perfect Support | Experimental support, adapted to the latest `experimental.skills` specification. | | **Codex** | ✅ Perfect Support | Supports `$skill` explicit invocation and implicit intent recognition. | --- ## 🏁 Quick Start > **Overall Route**: Install Unity Plugin → Start UnitySkills Server → AI Use Skill <p align="center"> <img src="docs/installation-demo.gif" alt="One-Click Installation Demo" width="800"> </p> ### 1. Install Unity Plugin Add Git URL directly through Unity Package Manager: **Stable Version Installation (main)**: ``` https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity ``` **Development Beta Version Installation (beta)**: ``` https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity#beta ``` **Specific Version Installation** (e.g., v1.4.0): ``` https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity#v1.4.0 ``` > 📦 All version packages can be downloaded from the [Releases](https://github.com/Besty0728/Unity-Skills/releases) page. ### 2. Start Service In Unity, click the menu: `Window > UnitySkills > Start Server` ### 3. One-Click Configuration of AI Skills 1. Open `Window > UnitySkills > Skill Installer`. 2. Select the corresponding terminal icon (Claude / Antigravity / Gemini / Codex). 3. Click **"Install"** to complete the environment configuration without manually copying code. > Installer file description (generated in the target directory): > - `SKILL.md` > - `scripts/unity_skills.py` > - `scripts/agent_config.json` (containing Agent identifier) > - Antigravity additionally generates `workflows/unity-skills.md` > **Codex Special Note**: Global installation is recommended. Project-level installation needs to be declared in `AGENTS.md` to be recognized. Restart Codex after global installation. 📘 For more complete installation and usage instructions, please see: [docs/SETUP_GUIDE.md](docs/SETUP_GUIDE.md) ### 4. Manually Install Skills (Optional) If one-click installation is not supported, you can manually deploy according to the following **standard process** (applicable to all tools that support Skills): #### ✅ Standard Installation Specification A 1. **Custom Installation**: In the installation interface, you can select the "Custom Path" option to install Skills to any directory you specify (e.g., `Assets/MyTools/AI`) for easy project management. #### ✅ Standard Installation Specification B 1. **Locate the Skills Source Directory**: The `unity-skills/` in this repository is the distributable Skills template (the root directory contains `SKILL.md`). 2. **Find the Tool's Skills Root Directory**: Different tools have different paths, prioritize the tool's documentation. 3. **Complete Copy**: Copy the entire `unity-skills/` directory to the tool's Skills root directory. 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 the AI tool you are using (e.g., `claude-code`, `antigravity`, `gemini-cli`, `codex`). 5. **Directory Structure Requirements**: After copying, the structure must be as follows (example): - `unity-skills/SKILL.md` - `unity-skills/skills/` - `unity-skills/scripts/unity_skills.py` - `unity-skills/scripts/agent_config.json` 6. **Restart Tool**: Allow the tool to reload the Skills list. 7. **Verify Loading**: Trigger the Skills list/command (or execute a simple skill call) within the tool to confirm availability. #### 🔎 Common Tool Directory Reference The following are verified default directories (if the tool has a custom path configured, please refer to the custom path): - Claude Code: `~/.claude/skills/` - Antigravity: `~/.agent/skills/` - Gemini CLI: `~/.gemini/skills/` - OpenAI Codex: `~/.codex/skills/` #### 🧩 Other Tools that Support Skills If you are using other tools that support Skills, please install according to the Skills root directory specified in the tool's documentation. As long as the **standard installation specification** is met (the root directory contains `SKILL.md` and maintains the `skills/` and `scripts/` structure), it can be correctly recognized. --- ## 📦 Skills Category Overview (431) | Category | Quantity | Core Functionality | | :--- | :---: | :--- | | **Cinemachine** | 23 | 2.x/3.x dual version auto-install/mixing camera/ClearShot/TargetGroup/Spline | | **Workflow** | 22 | Persistent history/task snapshot/session-level undo/rollback/bookmark | | **Material** | 21 | Batch modification of material properties/HDR/PBR/Emission/keywords/render queue | | **GameObject** | 18 | Create/find/transform sync/batch operations/hierarchy management/rename/copy | | **Scene** | 18 | Multi-scene loading/unloading/activation/screenshot/context/dependency analysis/report export | | **UI System** | 16 | Canvas/Button/Text/Slider/Toggle/anchor/layout/alignment/distribution | | **Asset** | 15 | Asset import/delete/move/copy/search/folder/batch operations/refresh | | **Editor** | 12 | Play mode/selection/undo redo/context acquisition/menu execution | | **Timeline** | 12 | Track creation/deletion/Clip management/playback control/binding/duration setting | | **Physics** | 12 | Ray detection/sphere casting/box casting/physics material/layer collision matrix | | **Audio** | 12 | Audio import settings/AudioSource/AudioClip/AudioMixer/batch | | **Texture** | 12 | Texture import settings/platform settings/Sprite/type/size lookup/batch | | **Model** | 12 | Model import settings/Mesh information/material mapping/animation/skeleton/batch | | **Script** | 12 | C# script creation/read/replace/list/information/rename/move/analysis | | **Package** | 11 | Package management/install/remove/search/version/dependency/Cinemachine/Splines | | **AssetImport** | 11 | Texture/model/audio/Sprite import settings/tag management/reimport | | **Project** | 11 | Render pipeline/build settings/package management/Layer/Tag/PlayerSettings/quality | | **Shader** | 11 | Shader creation/URP template/compilation check/keywords/variant analysis/global keywords | | **Camera** | 11 | Scene View control/Game Camera creation/properties/screenshot/orthographic switching/list | | **Terrain** | 10 | Terrain creation/heightmap/Perlin noise/smoothing/flattening/texture drawing | | **NavMesh** | 10 | Baking/path calculation/Agent/Obstacle/sampling/area cost | | **Cleaner** | 10 | Unused resources/duplicate files/empty folders/missing script repair/dependency tree | | **ScriptableObject** | 10 | Create/read and write/batch settings/delete/find/JSON import and export | | **Console** | 10 | Log capture/cleanup/export/statistics/pause control/folding/playback clear | | **Debug** | 10 | Error log/compilation check/stack/assembly/definition symbol/memory information | | **Event** | 10 | UnityEvent listener management/batch add/copy/state control/enumeration | | **Smart** | 10 | Scene SQL query/spatial query/automatic layout/align to ground/grid snapping/randomization/replacement | | **Test** | 10 | Test run/run by name/category/template creation/summary statistics | | **Prefab** | 10 | Create/instantiate/override apply and restore/batch instantiation/variant/find instances | | **Component** | 10 | Add/remove/property configuration/batch operations/copy/enable disable | | **Optimization** | 10 | Texture compression/mesh compression/audio compression/scene analysis/static marking/LOD/duplicate materials/overdraw | | **Profiler** | 10 | FPS/memory/texture/mesh/material/audio/rendering statistics/object count/AssetBundle | | **Light** | 10 | Light creation/type configuration/intensity color/batch switch/probe group/reflection probe/lightmap | | **Validation** | 10 | Project validation/empty folder cleanup/reference detection/mesh collision/Shader error | | **Animator** | 10 | Animation controller/parameters/state machine/transition/allocation/playback | | **Perception** | 9 | Scene summary/hierarchy tree/script analysis/spatial query/material overview/scene snapshot/dependency analysis/report export/performance tips | | **Sample** | 8 | Basic examples: create/delete/transform/scene information | > ⚠️ Most modules support `*_batch` batch operations. Batch Skills should be prioritized when operating on multiple objects to improve performance. --- ## 📂 Project Structure ```bash . ├── SkillsForUnity/ # Unity Editor Plugin (UPM Package) │ ├── package.json # com.besty.unity-skills │ └── Editor/Skills/ # Core Skill Logic (37 *Skills.cs, 431 Skills in total) │ ├── SkillsHttpServer.cs # HTTP Server Core (Producer-Consumer) │ ├── SkillRouter.cs # Request Routing & Reflection Discovery Skills │ ├── 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 (23 skills) │ ├── WorkflowSkills.cs # Workflow Undo/Rollback (22 skills) │ ├── PerceptionSkills.cs # Scene Understanding (9 skills) │ └── ... # 431 Skills Source Code ├── unity-skills/ # Cross-Platform AI Skill Template (Distributed to AI Tools) │ ├── SKILL.md # Main Skill Definition (Read by AI) │ ├── scripts/ │ │ └── unity_skills.py # Python Client Library │ ├── skills/ # Skill Documentation Categorized by Module │ └── references/ # Unity Development Reference Documentation ├── docs/ │ └── SETUP_GUIDE.md # Complete Installation and Usage Guide ├── CHANGELOG.md # Version Update History └── LICENSE # MIT Open Source License ``` --- ## ⭐ Star History [](https://star-history.com/#Besty0728/Unity-Skills&Date) --- ## 📄 Open Source License This project is licensed under the [MIT License](LICENSE).