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 inside the Unity editor. The server exposes 805 “Skills” (small, focused actions) as REST endpoints. AI‑powered coding assistants (Claude Code, Antigravity, Codex, Cursor, Kimi Code, OpenCode) can call these endpoints to create, modify, or delete Unity assets, scenes, prefabs, shaders, UI, physics, networking, XR setups, and many other editor tasks.

Why it matters – By moving editor operations behind a well‑defined API, UnitySkills lets large language models (LLMs) act as real Unity developers: they can issue concrete commands instead of just generating code snippets. The project adds safety layers (dry‑run planning, per‑operation permission modes, audit logs, transactional roll‑backs) that address the biggest concern with AI‑driven scene editing – accidental corruption.

Core capabilities

Feature	What you get
805 REST Skills	Over 800 ready‑made actions grouped into 54 categories (e.g., YooAsset, Cinemachine, Netcode, UI Toolkit, XR, ShaderGraph, etc.). Each skill is a tiny, documented HTTP call that can be scripted or invoked by an AI assistant.
Three‑tier permission system	Approval (human grants a token), Auto (full‑auto execution, high‑risk ops blocked), Bypass (unrestricted). Modes are configurable from the Unity panel and map to Claude Code’s permission model.
Dry‑run / planning mode	Append `?mode=dryRun` or `?mode=plan` to any endpoint to get parameter validation and an impact estimate without touching the project.
Transactional batch execution	`POST /skills/batch` runs a series of skills as a single transaction: fail‑fast, optional `continueOnError`, cross‑step `$ref`, automatic rollback on failure, and a `?diff=1` preview of net changes.
Audit trail	Every call, grant, revoke, and blocked request is written to `Library/UnitySkillsAudit.jsonl`. The log is viewable in‑panel, and deletions are also recorded.
Rollback granularity	Five snapshot types survive domain reloads; `workflow_undo_task` rolls back a single task, not the whole project.
Multi‑instance control	The server discovers free ports automatically and can manage several Unity projects at once via a global registry.
Long‑lived connections	Configurable timeout (default 15 min) and automatic reconnection after a domain reload.
Anti‑hallucination guardrails	Each skill ships with a “DO NOT” list and routing rules to keep the AI from issuing unsafe operations.

Supported AI terminals (one‑click install)

Terminal	Status
Antigravity	✅ (shares `.agents/skills/` with Codex)
Claude Code	✅
Codex	✅
Cursor	✅
Kimi Code	✅
OpenCode	✅

If you use a different tool, you can still install the skills manually (see the “Manual Skills Installation” section).

Quick start (three steps)

Add the Unity package – In the Package Manager, add the Git URL:
```
https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity
```
(or use the #beta or a tagged version for a specific release).
Start the server – Open Window → UnitySkills (or press Alt + Shift + U) and toggle the server switch. The server will survive domain reloads automatically.
Install the AI skill set – In the same panel, go to the AI Config tab, pick your terminal icon, and click Install. The installer copies the unity‑skills~/ template into the terminal’s skill directory, creates the required agent_config.json, and registers the skills with the AI tool.

Safety & governance

Pre‑execution preview – Use ?mode=dryRun/?mode=plan to see what a skill would change.
Permission gating – High‑risk operations (marked NeverInSemi) are blocked unless the user explicitly allows them via the Allowlist.
Structured logging – All activity is stored as JSONL, making it easy to audit or replay.
Rollback – Snapshots are content‑addressed; you can undo a single task or a whole batch without losing other work.

Who might use this?

Game developers who want LLMs to prototype level layouts, generate UI, or set up networking without writing boilerplate code.
Technical artists looking to batch‑process assets (e.g., YooAsset bundles, ShaderGraph tweaks, ProBuilder meshes) via AI commands.
Tool builders who need a stable, versioned API for integrating Unity with external automation pipelines.
Researchers exploring safe AI‑assisted content creation in a complex editor environment.

Where to learn more

Operating Modes & Governance – docs/OPERATING_MODES.md
Setup Guide – docs/SETUP_GUIDE.md (English) / docs/SETUP_GUIDE_CN.md (Chinese)
Skill catalogue – the “805 Skills Category Overview” section of the README lists every skill group and its core functions.

TL;DR

UnitySkills turns the Unity editor into a REST‑driven service that AI coding assistants can call safely. It ships with hundreds of ready‑made actions, a granular permission system, audit logging, and transactional roll‑backs, making AI‑guided scene editing practical for real projects.