Unity-Skills

# 🎮 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-277-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>基于 REST API 的 AI 驱动型 Unity 编辑器自动化引擎</b><br>
  <i>让 AI 通过Skills直接掌控 Unity 场景</i>
</p>

<p align="center">
  🎉 我们已被 <b>DeepWiki</b> 收录！<br>
  有问题？查阅 AI 生成的项目文档 → <a href="https://deepwiki.com/Besty0728/Unity-Skills"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
</p>

## 🤝 致谢
本项目基于 [unity-mcp](https://github.com/CoplayDev/unity-mcp) 的优秀理念深度重构与功能扩展。

---

## 🚀 核心特性

- ⚡ **极致效能**：支持 **Result Truncation** 与 **SKILL.md** 瘦身，最大化节省 Token。
- 🛠️ **全能工具库**：内置 277 Skills，支持 **Batch (批处理)** 操作，大幅减少 HTTP 通信开销，显著提升执行效率。
- 🛡️ **安全第一**：支持 **Transactional (事务原子性)**，操作失败自动回滚，场景零残留。
- 🌍 **多实例支持**：自动端口发现、全局注册表，支持同时控制多个 Unity 项目。
- 🤖 **深度集成**：独家支持 **Antigravity Slash Commands**，解锁 `/unity-skills` 交互新体验。
- 🔌 **全环境兼容**：完美支持 Claude Code, Antigravity, Gemini CLI 等主流 AI 终端。
- 🎥 **Cinemachine 2.x/3.x 双版本支持**：自动检测 Unity 版本并安装对应 Cinemachine，支持 **MixingCamera**, **ClearShot**, **TargetGroup**, **Spline** 等高级相机控制。

---

## 🏗️ 支持的 IDE / 终端

本项目针对以下环境进行了深度优化，确保持续、稳定的开发体验：

| AI 终端 | 支持状态 | 特色功能 |
| :--- | :---: | :--- |
| **Antigravity** | ✅ 完美支持 | 支持 `/unity-skills` 斜杠命令，原生集成工作流。 |
| **Claude Code** | ✅ 完美支持 | 智能识别 Skill 意图，支持复杂多步自动化。 |
| **Gemini CLI** | ✅ 完美支持 | 实验性支持，适配最新 `experimental.skills` 规范。 |
| **Codex** | ✅ 完美支持 | 支持 `$skill` 显式调用和隐式意图识别。 |

---

## 🏁 快速开始

### 1. 安装 Unity 插件
通过 Unity Package Manager 直接添加 Git URL：

**稳定版安装 (main)**:
```
https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity
```

**开发测试版安装 (beta)**:
```
https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity#beta
```

**指定版本安装** (如 v1.4.0):
```
https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity#v1.4.0
```

> 📦 所有版本包可在 [Releases](https://github.com/Besty0728/Unity-Skills/releases) 页面下载

### 2. 启动服务
在 Unity 中点击菜单：`Window > UnitySkills > Start Server`

### 3. 一键配置 AI Skills
1. 打开 `Window > UnitySkills > Skill Installer`。
2. 选择对应的终端图标（Claude / Antigravity / Gemini / Codex）。
3. 点击 **"Install"** 即可完成环境配置，无需手动拷贝代码。

> 安装器落盘文件说明（生成于目标目录）：
> - `SKILL.md`
> - `scripts/unity_skills.py`
> - `scripts/agent_config.json`（包含 Agent 标识）
> - Antigravity 额外生成 `workflows/unity-skills.md`

> **Codex 特别说明**：推荐使用**全局安装**。项目级安装需要在 `AGENTS.md` 中声明才能识别，全局安装后重启 Codex 即可。

📘 需要更完整的安装与使用说明，请查看：[docs/SETUP_GUIDE.md](docs/SETUP_GUIDE.md)

### 4. 手动安装 Skills（可选）
如果不支持不使用一键安装，可按以下**标准流程**手动部署（适用于所有支持 Skills 的工具）：

#### ✅ 标准安装规范A
1. **自定义安装**: 在安装界面，你可以选择 "Custom Path" 选项，将 Skills 安装到你指定的任意目录（例如 `Assets/MyTools/AI`），方便项目管理。

#### ✅ 标准安装规范B
1. **定位 Skills 源码目录**：本仓库的 `unity-skills/` 即为可分发的 Skills 模板（根目录包含 `SKILL.md`）。
2. **找到工具的 Skills 根目录**：不同工具路径不同，优先以该工具文档为准。
3. **完整复制**：将整个 `unity-skills/` 目录复制到工具的 Skills 根目录下。
4. **创建 agent_config.json**：在 `unity-skills/scripts/` 目录下创建 `agent_config.json` 文件：
   ```json
   {"agentId": "your-agent-name", "installedAt": "2026-02-11T00:00:00Z"}
   ```
   将 `your-agent-name` 替换为你使用的 AI 工具名称（如 `claude-code`、`antigravity`、`gemini-cli`、`codex`）。
5. **目录结构要求**：复制后需保持结构如下（示例）：
   - `unity-skills/SKILL.md`
   - `unity-skills/skills/`
   - `unity-skills/scripts/unity_skills.py`
   - `unity-skills/scripts/agent_config.json`
6. **重启工具**：让工具重新加载 Skills 列表。
7. **验证加载**：在工具内触发 Skills 列表/命令（或执行一次简单技能调用），确认可用。

#### 🔎 常见工具目录参考
以下为已验证的默认目录（若工具配置过自定义路径，请以自定义为准）：

- Claude Code：`~/.claude/skills/`
- Antigravity：`~/.agent/skills/`
- Gemini CLI：`~/.gemini/skills/`
- OpenAI Codex：`~/.codex/skills/`

#### 🧩 其他支持 Skills 的工具
若你使用的是其他支持 Skills 的工具，请按照该工具文档指定的 Skills 根目录进行安装。只要满足**标准安装规范**（根目录包含 `SKILL.md` 并保持 `skills/` 与 `scripts/` 结构），即可被正确识别。

---

## 📦 Skills 分类概要 (277)

| 分类 | 数量 | 核心功能 |
| :--- | :---: | :--- |
| **Material** | 21 | 材质属性批量修改/HDR/PBR设置 |
| **GameObject** | 18 | 创建/查找/变换同步/批量操作/层级管理 |
| **Editor** | 12 | 播放模式/选择/撤销重做/上下文获取 |
| **Asset** | 11 | 资产导入/搜索/文件夹/GUID管理 |
| **UI System** | 11 | Canvas/Button/Text/Slider/RectTransform |
| **Component** | 8 | 添加/移除/属性配置/复制粘贴 |
| **Animator** | 8 | 动画控制器/参数/状态机/过渡 |
| **Sample** | 8 | 示例场景/测试用例生成 |
| **Light** | 7 | 灯光创建/类型配置/强度颜色/批量开关 |
| **Validation** | 7 | 项目验证/空文件夹清理/引用检测 |
| **Terrain** | 6 | 地形创建/高度图编辑/纹理绘制 [v1.4] |
| **Perception** | 3 | 场景摘要/层级描述/脚本分析 [v1.4] |
| **Smart** | 3 | 场景查询/自动布局/引用装配 [v1.5 NEW] |
| **UI Layout** | 5 | 锚点/尺寸/布局组/对齐/分布 [v1.5 NEW] |
| **Scene** | 6 | 场景切换/保存/加载/截图 |
| **Script** | 6 | C# 脚本创建/编译检查/搜索 |
| **Shader** | 6 | Shader 查找/创建/属性列举 |
| **Workflow** | 6 | **[NEW]** 持久化历史/回滚/快照/标签管理 [v1.4] |
| **DebugEnhance** | 4 | 控制台日志/清空/错误暂停 [v1.4] |
| **AssetImport** | 4 | 重新导入/贴图设置/模型设置 [v1.4] |
| **Cleaner** | 5 | 未使用资源/重复文件/丢失引

... (truncated)