# UnitySkills: A REST API Layer That Lets AI Drive Unity Editor with Governance Built In

> UnitySkills exposes 805 REST skills for AI agents to control Unity scenes, adding permission modes, audit trails, and rollback that typical MCP bridges lack. It targets Unity 2022.3+ and Unity 6, with a trade-off in setup complexity and a narrower IDE installer list.

**Besty0728/Unity-Skills** — AI automation skills specifically designed for Unity

- Repository: https://github.com/Besty0728/Unity-Skills
- Website: https://www.micostar.cc
- Stars: 1,878 · Forks: 171
- Language: C#
- License: MIT
- Published: 2026-08-22 · Updated: 2026-08-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/besty0728-unity-skills

## What UnitySkills Actually Solves

UnitySkills addresses a specific gap: letting an AI agent edit Unity scenes, prefabs, and .meta files without giving it unrestricted write access. The README positions it as a REST API-based AI-driven Unity Editor Automation Engine. The problem it solves is not just automation; it is control. Without a governance layer, an AI that calls Unity tools can corrupt a scene or leave stray changes. UnitySkills provides a server that exposes skills as REST endpoints, with permission checks, audit logging, and rollback. The target user is a developer or team using an AI coding terminal like Claude Code, Codex, or Cursor, who wants the AI to manipulate Unity assets but needs guardrails. It is not for someone who wants a simple scriptable editor; it is for AI-driven workflows where mistakes are likely and must be contained.

## The REST Skill Architecture and Data Flow

UnitySkills works as a server inside the Unity Editor. The README describes 805 REST skills across 54 categories, backed by 56 source files, plus 28 advisory design modules. The data flow is: an AI terminal sends an HTTP request to the UnitySkills server, which runs in the Editor. The server validates parameters, checks the permission mode, and either executes the skill or returns a grant token for approval. Each skill carries risk metadata, which drives gating. The server supports batch operations via POST /skills/batch, which runs as a transaction with cross-step $ref, rollback on failure, and a diff query parameter to show net changes. There is also a dryRun and plan mode that returns parameter validation and an impact estimate without writing anything. This is a different model from a typical MCP bridge, where the AI calls tools directly with no permission layer. The server also handles multiple Unity instances through automatic port discovery and a global registry, and it recovers after Domain Reload with configurable timeouts, defaulting to 15 minutes.

## Getting It Running: Installation and Modes

The README lists quick installers for six IDEs: Claude Code, Antigravity, Codex, Cursor, OpenCode, and Kimi Code. For those, installation is one-click. For other terminals, you use a Custom Installation path, and per-tool skill directories are listed in the Manual Installation section. After installation, you open the Unity panel via Window > UnitySkills. The Settings panel has a Server section where you switch permission modes. There are three modes: Approval, Auto, and Bypass. Approval requires the AI to get a grant token and wait for user approval before executing. Auto is the default for new installs: FullAuto skills run directly, but high-risk operations are auto-blocked. Bypass is the default for existing installs that upgrade, preserving prior Full-Auto behavior. The README notes that chat trigger words are no longer supported; mode switching only happens in the panel. There is also an Allowlist for persistent per-skill passes, and a dual approval channel via dialog or panel.

## Governance: Permissions, Audit, and Rollback

The governance layer is the core differentiator. Before execution, you can use dryRun or plan mode to preview parameter validation and impact. At execution, the server derives high-risk gating from each skill's risk metadata, so gating does not depend on the AI behaving well. After execution, every call, grant, revoke, and blocked hit lands in a JSONL audit trail stored at Library/UnitySkillsAudit.jsonl, browsable in the panel. Deletions are audited too. After a mistake, there are five types of persistent snapshots that survive Domain Reloads, and a workflow_undo_task skill rolls back one task, not the whole project. The batch endpoint runs as a transaction, which is rare among AI tool bridges. The README compares this to a typical MCP bridge, which has no permission model and relies on Unity's native Undo stack that may not survive a Domain Reload. It also compares to Unity's official AI Assistant, which uses per-client trust and project-wide checkpoints. The comparison table is explicit about what UnitySkills offers: per-operation granularity, structured audit, per-task rollback, and pre-execution preview.

## Limitations and Wrong-Tool Cases

UnitySkills is not the right tool if you are on Unity 2021. The README states the official maintenance baseline is Unity 2022.3+, with some 2021 compatibility logic remaining but no future testing or adaptation. So a Unity 2021 project is a risk. Another limitation is the installer list: only six IDEs have quick installers. If you use a different AI terminal, you must use Custom Installation, which likely means manual configuration. The README does not detail that process, so it could be a barrier. There is also a conceptual trade-off: the permission system adds friction. In Approval mode, every operation needs a grant token, which slows down AI-driven workflows. In Bypass mode, you lose the safety net, and only an optional high-risk confirmation gate remains. The README claims the system is transactional and rolls back failed operations, but it does not describe failure modes for the rollback itself, such as what happens if the rollback fails or if the snapshot is corrupted. That is an unknown. Also, the project is a refactoring of unity-mcp, so it inherits that project's assumptions about how AI tools should connect to Unity.

## Alternatives and How They Differ

The README itself names two alternatives. The first is a typical MCP bridge, such as the original unity-mcp that this project refactors. An MCP bridge exposes Unity tools as callable functions to an AI, but it has no permission model: once connected, the whole tool surface is callable. It relies on Unity's native Undo stack for rollback, which is not guaranteed to survive a Domain Reload. The second alternative is Unity's official AI Assistant, which uses per-client trust through a Pending Connections list. After you approve a client, calls are not distinguished by operation, and rollback is project-wide checkpoints that rewind the entire project. UnitySkills differs by adding per-skill risk metadata, a three-tier permission mode, structured JSONL audit, and per-task rollback. The comparison table is useful, but note that the README says the other two columns are based on public material surveyed in 2026-07 and may have changed. So if you evaluate alternatives, verify their current capabilities.

## Maintenance, Upgrade, and License Considerations

The project is MIT licensed, which means you can use, modify, and redistribute it with attribution, but the README does not give legal advice on compliance. For maintenance, the release history shows active development: v2.7.1, v2.7.0, and v2.6.2 were pushed within a week in August 2026. The README states the maintenance baseline is Unity 2022.3+ / Unity 6, and future work will focus there. Upgrade behavior is handled: existing installs are detected and stay on Bypass mode to preserve prior behavior. That is a thoughtful touch, but it also means an upgrade could silently keep a permissive mode. The audit log is stored in Library/UnitySkillsAudit.jsonl, which is a project-local path, so you need to account for that in version control or backup. The README mentions DeepWiki indexing for AI-generated docs, which could help, but it is not a substitute for reading the source. The codebase is in C#, and the repository has 56 source files for skills, so the maintenance cost for a fork could be moderate. There is no mention of a contribution guide or issue tracker in the provided material, but the project is not archived and has recent releases.

## Conclusion

Adopt UnitySkills if you need an AI agent to edit Unity scenes and prefabs with per-operation permission controls, structured audit logs, and rollback that survives Domain Reloads, and if you target Unity 2022.3+ or Unity 6. Skip it if you rely on Unity 2021 or if you need a quick installer for a terminal not on the supported list; you would then use Custom Installation. Before adopting, verify the permission mode default (Auto for new installs, Bypass for upgrades) matches your safety needs, and test the dryRun and plan modes on a non-production scene to confirm the rollback behavior and audit log path (Library/UnitySkillsAudit.jsonl) work as documented.

## FAQ

### What are UnitySkills?

A REST API based engine that lets an AI tool drive the Unity Editor directly, with 805 REST skills across 54 categories in 56 source files, 28 advisory design modules and batch operations. It is a deep refactoring of unity-mcp, MIT licensed, and its maintenance baseline is Unity 2022.3+.

### Which permission mode does UnitySkills use by default?

It depends on the install. New installs default to Auto, where full-auto skills run directly and NeverInSemi high-risk operations are blocked. Upgrading installs are detected automatically and stay on Bypass, where all skills run unrestricted. Switching happens in the Unity panel under Window > UnitySkills, Settings, Server.

### What does dry run mode do in UnitySkills?

Appending `?mode=dryRun` or `?mode=plan` to a call returns parameter validation and an impact estimate and writes nothing, so the operation can be rehearsed before the model executes it against a real scene.

### How do you undo a mistake an AI made in your Unity project?

Five types of persistent snapshot survive Domain Reloads, and `workflow_undo_task` rolls back a single task rather than the whole project. `POST /skills/batch` runs as a transaction with cross-step `$ref` values, rollback on failure and a `?diff=1` net change view.

### Where is the UnitySkills audit log stored?

In `Library/UnitySkillsAudit.jsonl` inside the Unity project, as JSONL with one record per call, grant, revoke and blocked hit, deletions included. The in-panel browser reads the same file, and the README describes no export step for moving it elsewhere.

## Sources

- [Official documentation](https://www.micostar.cc)
- [Official README](https://github.com/Besty0728/Unity-Skills#readme)
- [Project repository](https://github.com/Besty0728/Unity-Skills)
- [Release notes](https://github.com/Besty0728/Unity-Skills/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/besty0728-unity-skills