🎮 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

• 🛠️ 513 REST Skills Comprehensive Toolkit: Includes 14 advisory design modules with Batch operations for multi-object control.
• 🎛️ Dual-Mode Flexibility: Switch between Semi-Auto (code-first) and Full-Auto (direct manipulation) for different workflows.
• 🤖 4 Major IDEs Native Support: Claude Code / Antigravity / Gemini CLI / Codex — 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

Mode	Default	Available Skills	Use Case
Semi-Auto	✅	~80	AI writes C# code + light Skills assist (script, perception, scene, editor, asset, workflow, debug)
Full-Auto	—	All 513	AI directly manipulates Unity (create objects, configure materials/lights/UI, build scenes)

How to switch:

• → Full-Auto: "full auto" / "full-auto mode" / "build the scene for me" / "directly manipulate Unity"
• → Semi-Auto: "semi-auto" / "code-first" — each new session defaults to Semi-Auto

14 advisory design modules (architecture, performance, design patterns, testability, etc.) are available in both 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	Supports /unity-skills slash commands with native workflow integration.
Claude Code	✅ Supported	Intelligent Skill intent recognition, supports complex multi-step automation.
Gemini CLI	✅ Supported	Experimental support, adapted to the latest experimental.skills specification.
Codex	✅ Supported	Supports $skill explicit invocation and implicit intent recognition.

---

🏁 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 / Gemini / Codex).
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)
• Antigravity additionally generates workflows/unity-skills.md

Codex Note: Global installation is recommended. Project-level installation requires declaration in AGENTS.md to be recognized; after global installation, restart Codex to use.

📘 For complete installation and usage instructions, see: docs/SETUP_GUIDE.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:

   {"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, gemini-cli, codex).
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: ~/.agent/skills/
• Gemini CLI: ~/.gemini/skills/
• OpenAI Codex: ~/.codex/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.

---

📦 Skills Category Overview (513)

Category	Count	Core Functions
Cinemachine	23	2.x/3.x dual version auto-install/MixingCamera/ClearShot/TargetGroup/Spline
Workflow	22	Persistent history/Task snapshots/Session-level undo/Rollback/Bookmarks
Material	21	Batch material property modification/HDR/PBR/Emission/Keywords/Render queue
GameObject	18	Create/Find/Transform sync/Batch operations/Hierarchy management/Rename/Duplicate
Scene	10	Multi-scene load/Unload/Activate/Screenshot/Context/Dependency analysis/Report export
UI System	16	Canvas/Button/Text/Slider/Toggle/Anchors/Layout/Alignment/Distribution
UI Toolkit	15	UXML/USS file management/UIDocument/PanelSettings full property read-write/Template generation/Structure inspection/Batch create
Asset	11	Asset import/Delete/Move/Copy/Search/Folders/Batch operations/Refresh
Editor	12	Play mode/Selection/Undo-Redo/Context retrieval/Menu execution
Timeline	12	Track create/Delete/Clip management/Playback control/Binding/Duration
Physics	12	Raycast/SphereCast/BoxCast/Physics materials/Layer collision matrix
Audio	10	Audio import settings/AudioSource/AudioClip/AudioMixer/Batch
Texture	10	Texture import settings/Platform settings/Sprite/Type/Size search/Batch
Model	10	Model import settings/Mesh info/Material mapping/Animation/Skeleton/Batch
Script	12	C# script create/Read/Replace/List/Info/Rename/Move/Analyze
Package	11	Package management/Install/Remove/Search/Versions/Dependencies/Cinemachine/Splines
AssetImport	11	Texture/Model/Audio/Sprite import settings/Label management/Reimport
Project	11	Render pipeline/Build settings/Package management/Layer/Tag/PlayerSettings/Quality
Shader	11	Shader create/URP templates/Compile check/Keywords/Variant analysis/Global keywords
Camera	11	Scene View control/Game Camera create/Properties/Screenshot/Orthographic toggle/List
Terrain	10	Terrain create/Heightmap/Perlin noise/Smooth/Flatten/Texture painting
NavMesh	10	Bake/Path calculation/Agent/Obstacle/Sampling/Area cost
Cleaner	10	Unused assets/Duplicate files/Empty folders/Missing script fix/Dependency tree
ScriptableObject	10	Create/Read-Write/Batch set/Delete/Find/JSON import-export
Console	10	Log capture/Clear/Export/Statistics/Pause control/Collapse/Clear on play
Debug	10	Error logs/Compile check/Stack trace/Assemblies/Define symbols/Memory info
Event	10	UnityEvent listener management/Batch add/Copy/State control/List
Smart	10	Scene SQL query/Spatial query/Auto layout/Snap to ground/Grid snap/Randomize/Replace
Test	10	Test run/Run by name/Categories/Template create/Summary statistics
Prefab	11	Create/Instantiate/Override apply & revert/Batch instantiate/Variants/Find instances/Asset property editing
Component	10	Add/Remove/Property config/Batch operations/Copy/Enable-Disable
Optimization	10	Texture compression/Mesh compression/Audio compression/Scene analysis/Static flags/LOD/Duplicate materials/Overdraw
Profiler	10	FPS/Memory/Texture/Mesh/Material/Audio/Rendering stats/Object count/AssetBundle
Light	10	Light create/Type config/Intensity-Color/Batch toggle/Probe groups/Reflection probes/Lightmaps
Validation	10	Project validation/Empty folder cleanup/Reference detection/Mesh collider/Shader errors
Animator	10	Animation controller/Parameters/State machine/Transitions/Assign/Play
Perception	11	Scene summary/Hierarchy tree/Script analysis/Spatial query/Material overview/Scene snapshot/Dependency analysis/Report export/Performance hints/Script dependency graph
Sample	8	Basic examples: Create/Delete/Transform/Scene info

⚠️ Most modules support *_batch batch operations. When operating on multiple objects, prioritize batch Skills for better performance.

🧠 unity-skills/skills/ also includes 14 advisory design modules for architecture, script design, performance, maintainability, and Inspector guidance.

---

📂 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/                 # Modular Skill Documentation + 13 advisory modules
│   │   └── references/             # Unity Development References
│   └── Editor/Skills/              # Core Skill Logic (40 *Skills.cs files, 513 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 (23 skills)
│       ├── WorkflowSkills.cs       # Workflow Undo/Rollback (22 skills)
│       ├── PerceptionSkills.cs     # Scene Understanding (11 skills)
│       └── ...                     # 513 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.