unity-skills
GitHub通过本地 REST API 自动化 Unity 编辑器，支持脚本创建、场景编辑、资产管理及测试运行。需先检查健康状态与操作模式，按意图选择 Schema 层获取参数，执行前强制 dryRun 防幻觉。
Trigger Scenarios
Install
npx skills add Besty0728/Unity-Skills --skill unity-skills -g -y
SKILL.md
Frontmatter
{
"name": "unity-skills",
"description": "Automate the Unity Editor through a local REST API — create and edit scripts, build scenes and prefabs, manage assets\/materials\/lighting, run tests, and drive hundreds of Editor operations across modules. Use when the user wants to actually operate the Unity Editor from chat — create or modify GameObjects\/scripts\/scenes\/assets, batch-edit, or run Editor automation — in any language. Not needed for conceptual Unity Q&A that touches no Editor state — read the matching advisory doc under skills\/ instead. 当用户要从对话里实际操作 Unity 编辑器（创建\/修改\/批量编辑\/运行测试）时使用，任何语言均可触发；纯概念问答无需本协议。",
"compatibility": "Requires Unity Editor 2022.3+\/6000.x with the UnitySkills package (local REST server on localhost:8090-8100); Python 3 for the bundled client"
}
Unity Skills
All module and reference docs below are English-only. Match the user's request to modules by meaning, regardless of the user's language, and always reply in the user's language. Pure conceptual Unity Q&A that touches no Editor state → do not load this protocol; read the matching advisory doc under
skills/instead.
First Contact Checklist
Before the first skill call in a session:
GET /health— discover the server (ports8090–8100) and readcurrentMode("approval"/"auto"/"bypass"),panelApprovalRequired, andpendingCount.- Branch on
currentMode: underapproval, the first write call to anyFullAutoskill returnsMODE_RESTRICTEDand you must run the grant protocol before it executes; underauto/bypass, writes execute directly (self-assess risk underauto). Full protocol and mode table: see "Operating Mode" → "Boot Handshake" below. - Only then proceed to skill discovery (below) and calls.
Schema: pick the cheapest layer
All layers are server-cached with ETag/304 and served off the main thread; send Accept-Encoding: gzip.
| Layer | Endpoint | Size | Use when |
|---|---|---|---|
Default: start from GET /skills/recommend?intent=...&includeSchema=true |
~2–5 KB | Specific intent; returns scored candidates with parameter schemas. | |
| brief + category | GET /skills?brief=1 then GET /skills/schema?category=<Category> |
~19 KB + 13–44 KB | Task touches one or two areas. |
| summary | GET /skills?summary=1 |
~143 KB | Exploratory / cross-module / cheaper layers left you unsure. |
| full | GET /skills/schema |
~618 KB | Rare; many modules' exact signatures at once. |
dryRun gate and anti-hallucination rules
Before executing any skill whose exact parameters you don't already hold, dryRun it: POST /skill/<name>?mode=dryRun. Iterate until valid: true, then execute without ?mode=dryRun.
| Rule | Requirement |
|---|---|
| Uncertain parameters | Must dryRun first. Never guess parameters from a skill name. |
| Skill name mismatch | If the name does not appear in schema/recommend results, do not invent it. |
| Call failure | Read suggestedFixes; when pointed to a module doc, actually read it. |
Operating Mode
Three server-side permission gates: Approval (first FullAuto call needs a grant), Auto (executes directly, self-assess risky batches), Bypass (executes directly). Grants are single-shot per call; permanent bypass is the user-managed Allowlist. Details → operating mode.
Module routing by category
Load the matching module SKILL.md for guardrails and minimal examples; use schema/recommend for exact signatures, not module docs.
| Category | Modules |
|---|---|
| GameObject & Scene | gameobject, scene, prefab, component, terrain, navmesh |
| UI | ui, uitoolkit |
| Rendering & URP | material, shader, shadergraph, light, graphics, urp, volume, decal, postprocess |
| Animation & Camera | animator, timeline, cinemachine, camera |
| Physics & Behavior | physics, behavior |
| Scripting & Testing | script, test, debug, console, validation, smart |
| Assets & Packages | asset, importer, package, scriptableobject |
| Tween & Modeling | dotween, primetween, probuilder |
| Networking | netcode |
| Hot-update & Bundles | hybridclr, yooasset |
| Editor & Workflow | editor, project, profiler, workflow, batch, cleaner, event, optimization, perception, sample |
| XR | xr |
| Advisory & design docs | architecture, patterns, performance, *-design (8), and more → see index |
| Manual tasks (docs-only) | manual-gameobject, manual-component, manual-material, manual-scene |
| Full index (all 79 modules) | → module index |
guideMode
If /health returns guideMode: true, read SKILL_GUIDE.md and give manual steps for simple tasks instead of calling REST.
Error codes quick reference
| Code | Meaning | Pointer |
|---|---|---|
MODE_RESTRICTED |
Approval mode: FullAuto skill needs a user grant. | Grant protocol → operating mode |
MODE_FORBIDDEN |
Skill is NeverInSemi; needs Bypass or Allowlist. |
Details → operating mode |
MISSING_PARAM |
Required parameter omitted. | Get schema via dryRun; full list → error codes |
TARGET_NOT_FOUND |
GameObject / asset / component not found. | Locate first; full list → error codes |
COMPILING / RATE_LIMIT / QUEUE_FULL / SERVER_STOPPED |
Transient; Python client auto-retries. | Full list → error codes |
Observability and Unity CLI pointers
- Compilation status, events, analytics → observability
- Unity CLI cold start (opt-in, v2.3+) → unity-cli
Current snapshot: 784 REST skills, 54 functional source modules, 79 module documentation directories (50 REST/module docs + 29 advisory docs), Unity 2022.3+, default timeout 15 minutes.
Python helper: unity-skills/scripts/unity_skills.py
Version History
-
5ee8388
Current 2026-08-17 04:09
精简根文档至6.2KB，协议细节移至参考文件；新增引导模式文档及多个手动模块建议；为Top10 REST模块添加常见错误说明；版本号升级至2.6.0。
-
25d511e
2026-08-13 09:12
修正技能数量统计，将重复计数的 817 更正为实际注册的 784 个，同步更新相关文档与版本信息。
-
e49379b
2026-07-31 06:53
1. 新增会话首次接触的Health检查和Mode分支逻辑；2. 修复SKILL.md诱导Agent错误调用Python helper函数（如get_skill_schema）及存在25个幽灵Skill名的严重Bug；3. 更新SemiAuto模块清单为真实存在的Skill名；4. 优化Schema分层查询策略说明，强调缓存与压缩以减少Token消耗。
-
14e175d
2026-07-19 18:04
v2.1.1: 新增 PrimeTween Free 技能；修复 PackageInfo 二义性、FindType 复用及 .meta 补录问题，技能总数增至 738。v2.1.0: 引入分层 Schema 查询策略以优化成本，强化 dryRun 模式校验，替换宏控制为编辑器变更追踪。
- ec9f870 2026-07-05 14:38
