Besty0728/Unity-Skills

UnitySkills – AI‑driven REST API for Unity Editor Automation

What it is – UnitySkills is a Unity 2022.3+ plugin that runs a local HTTP server exposing Skills (pre‑written editor commands) as REST endpoints. An external AI‑assistant (Claude Code, Antigravity, Codex, Cursor, OpenCode, etc.) can call these endpoints to create, modify, or delete scenes, prefabs, assets, and .meta files on behalf of the user.

Core ideas

Layer	What it does
Skills catalog	784 “Skill” modules grouped into 25 advisory design modules (e.g., UI, Netcode, XR, ShaderGraph). Each Skill is a small, typed operation that knows its required parameters, risk level, and whether it mutates the scene or assets.
REST interface	`POST /skill/{name}` (single) or `POST /skills/batch` (transactional). Supports query parameters `?mode=dryRun` or `?mode=plan` to preview validation errors and an impact estimate without touching the project.
Permission system	Three modes – Approval, Auto, Bypass – mirroring Claude Code’s permission model. Per‑skill metadata (`RiskLevel`, `MayEnterPlayMode`, etc.) gates execution. An optional `ConfirmationToken` adds a second user‑approval step for high‑risk calls.
Audit & rollback	Every request, grant, revoke, and blocked call is appended to `Library/UnitySkillsAudit.jsonl` (rotates at 1 MiB). Snapshots of each file change are stored content‑addressed under `Library/UnitySkills/`, allowing a typed `workflow_undo_task` to roll back a single operation even after a domain reload.
Batch transactions	`POST /skills/batch` can be fail‑fast or continueOnError, supports `$ref` to reuse earlier step output, and can automatically roll back on failure. The `?diff=1` flag returns the net file‑system diff of the whole batch.
Long‑lived connections	Configurable timeout (default 15 min), automatic reconnection after domain reloads, and retry hints while Unity recompiles scripts.
Anti‑hallucination guardrails	Each Skill ships with “DO NOT” lists and routing rules that reject calls to unknown commands or malformed parameters before they reach the editor.

How it works (high‑level flow)

Install the Unity package via the Unity Package Manager using the Git URL (stable, beta, or a tagged version). The package adds the Window → UnitySkills panel and the server code under Library/UnitySkills.
Start the server from the panel (or with the toggle shortcut Alt+Shift+U). The server automatically restarts after any domain reload.
Configure an AI terminal – in the panel’s AI Config tab pick Claude Code, Antigravity, Codex, Cursor, or OpenCode and click Install. The installer copies a template skill‑bundle (unity‑skills~/) into the terminal’s skill directory and writes an agent_config.json that identifies the AI agent.
The AI calls a Skill – e.g. POST /skill/createGameObject?mode=plan with JSON body { "name": "Enemy", "position": [0,1,0] }. The server validates parameters, returns a plan (or errors), and, if the user has granted permission, executes the operation in the Unity editor.
Audit & rollback – every call is logged; the user can view the log from the panel, filter entries, or delete them (deletions themselves are logged). If a mistake occurs, the user runs POST /skill/workflow_undo_task with the snapshot ID to revert just that change.

Quick‑start checklist

Step	Command / UI action
1️⃣ Install	Unity Package Manager → Add package from Git URL → `https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity` (or `#beta`, `#v1.6.0`, etc.)
2️⃣ Start server	`Window → UnitySkills` → toggle Server on (or `Alt+Shift+U`)
3️⃣ Link AI	In the same panel go to AI Config, pick your terminal, click Install
4️⃣ Test a skill	`curl -X POST http://localhost:5000/skill/createGameObject?mode=plan -d '{"name":"Test","position":[0,0,0]}'`
5️⃣ Review	Open Audit Log from the gear icon in the panel to see the request and its outcome

Who might use it

Game developers who want AI‑assisted level design, bulk asset tweaking, or rapid prototyping without manually clicking through the editor.
CI/CD pipelines that need deterministic, scriptable Unity edits (e.g., auto‑generating prefabs, updating package versions) while keeping a full audit trail.
Tool builders creating custom AI agents that manipulate Unity projects – the REST contract makes integration language‑agnostic.
Large teams that require fine‑grained permission control (Approval mode) and rollback safety for AI‑generated changes.

Limitations & gotchas (as documented)

The server is local only; exposing it publicly would require additional security layers.
During a domain reload or script recompilation the REST endpoint is temporarily unavailable (the client must retry after a short pause).
Only Unity 2022.3+ is officially supported; some legacy 2021 code remains but will not receive new features.
Permission defaults differ for new vs. existing installations (new installs start in Auto, upgrades keep Bypass to preserve prior behavior).
The AI must understand the Skill catalog; unsupported terminals will need a custom installation of the skill files.

Where to find more

Docs – docs/SETUP_GUIDE.md (English) and docs/SETUP_GUIDE_CN.md (Chinese) for full installation steps.
Release assets – all versioned packages are on the GitHub Releases page.
DeepWiki docs – auto‑generated documentation at https://deepwiki.com/Besty0728/Unity-Skills.
License – MIT (see LICENSE).

Bottom line – UnitySkills turns the Unity editor into a trustworthy, auditable, REST‑driven automation surface that AI agents can call safely, with built‑in risk gating, dry‑run previews, and per‑operation rollback. It is a genuine software project aimed at AI‑augmented game development.