pi-unity-skill

An Agent Skill for pi that lets you develop Unity projects entirely from the terminal. Create projects, edit C# scripts, manipulate scenes and prefabs as YAML, compile, test, build, profile, and debug — all through CLI commands that your AI coding agent drives directly.

Built for workflows where you live in the terminal with pi or Claude Code, and Unity runs alongside as a controllable process.

What it does

Capability	How
Create projects	Pre-configured with Force Text serialization, Visible Meta Files, Vulkan, .gitignore, CLAUDE.md
Edit scripts	Direct .cs editing → recompile → error check, all from terminal
Inspect the editor	Run arbitrary C# inside Unity via unity-ctrl exec
Edit scenes & prefabs	Unity files are YAML — read, grep, edit, diff them as text
Play / stop / pause	Control the editor play mode from CLI
Run tests	EditMode and PlayMode tests via CLI or batch mode
Build	Headless builds via batch mode with custom build methods
Debug	Console logs, profiler hierarchy, screenshots — all CLI
Custom tools	Create project-specific [UnityCliTool] commands the agent discovers automatically

Prerequisites

• Unity 6.4 (6000.4.1f1) or later, installed via Unity Hub
• unity-ctrl — single binary CLI to control a running Unity Editor
• unity-cli (npm) — for Unity Hub operations
• Ubuntu 22.04+ with NVIDIA GPU and Vulkan (tested on RTX 2080 Super, but any Vulkan-capable GPU works)

Quick prerequisite install

# unity-ctrl (Go binary — direct editor control)
curl -fsSL https://github.com/youngwoocho02/unity-cli/releases/latest/download/unity-cli-linux-amd64 -o unity-ctrl
chmod +x unity-ctrl && sudo mv unity-ctrl /usr/local/bin/unity-ctrl

# unity-cli (npm — Hub management)
npm install -g @rage-against-the-pixel/unity-cli

Install

Global (all projects)

# Clone into pi's global skills directory
mkdir -p ~/.pi/agent/skills
git clone https://github.com/prodmodfour/pi-unity-skill.git ~/.pi/agent/skills/unity

Per-project

# Clone into the project skills directory
mkdir -p .pi/skills
git clone https://github.com/prodmodfour/pi-unity-skill.git .pi/skills/unity

Via pi settings

Add to ~/.pi/agent/settings.json or .pi/settings.json:

{
  "skills": ["path/to/pi-unity-skill"]
}

Via CLI flag

pi --skill path/to/pi-unity-skill

Usage

Once installed, pi discovers the skill automatically. It loads when your task involves Unity development, or you can invoke it explicitly:

/skill:unity
/skill:unity create a 2D platformer
/skill:unity add a health system to the player

Example session

You: /skill:unity create a new 3D project called SpaceGame

pi: [creates project with unity-init-project, adds Connector package,
     opens Unity, verifies connection with unity-ctrl status]

You: add a player spaceship that moves with WASD and rotates with mouse

pi: [creates Assets/Scripts/PlayerShip.cs, triggers recompilation,
     uses unity-ctrl exec to create a GameObject with the script,
     checks console for errors, saves the scene]

You: the ship feels too slow, and there's a jitter when rotating

pi: [reads PlayerShip.cs, adjusts moveSpeed field, changes rotation
     to FixedUpdate, recompiles, checks console, runs play mode to
     verify via unity-ctrl editor play --wait]

Skill structure

unity/
├── SKILL.md                        # Main skill instructions (loaded on /skill:unity)
├── references/
│   ├── cli-commands.md             # Full unity-ctrl command reference
│   ├── yaml-editing.md             # Guide to reading/editing Unity YAML safely
│   └── custom-tools.md             # Creating [UnityCliTool] project commands
└── scripts/
    ├── preflight.sh                # Check a project's CLI readiness
    ├── add-connector.sh            # Add Connector package to manifest.json
    └── fix-settings.sh             # Fix serialization/meta/graphics settings

The main SKILL.md is always loaded. Reference docs are loaded on-demand by the agent when it needs deeper detail — keeping context lean.

Key concepts

Force Text serialization

The most important setting. When enabled (m_SerializationMode: 2), Unity stores all .unity scenes, .prefab files, .asset configs, and .mat materials as human-readable YAML instead of binary. This means your agent can:

• Read scene files to understand what's in them
• Grep across all scenes/prefabs for specific objects or components
• Edit values directly (positions, field values, names, tags)
• Diff changes in version control

The unity-init-project command and fix-settings.sh script both enable this automatically.

The Connector package

unity-ctrl communicates with Unity through a lightweight Connector package that runs an HTTP server inside the editor. The skill's add-connector.sh script adds it to any project. Once installed, 80+ CLI commands become available — compile, test, execute C#, screenshot, profile, and more.

Reserialize after YAML edits

Unity's YAML serializer is strict. After editing any .unity, .prefab, .asset, or .mat file as text, always run:

unity-ctrl reserialize Assets/Path/To/File.unity

This loads the file through Unity's serializer and writes it back clean — fixing field order, indentation, and catching errors before they become silent corruption.

Helper commands

These are standalone shell commands installed separately from the skill (see the installation guide for unity-ctrl):

Command	Description
unity -projectPath <path>	Launch Unity Editor (forces Vulkan)
unity-batch <path> [args]	Run Unity headless (builds, tests, imports)
unity-init-project <path>	Create a new project with CLI-friendly settings
unity-ctrl <command>	Control a running Unity Editor
unity-cli hub -- <args>	Unity Hub CLI operations

Compatibility

• OS: Ubuntu 22.04+ (tested), likely works on other Linux distros and macOS
• Unity: 6.4 (6000.4.1f1) — paths in the skill reference this version; edit SKILL.md if yours differs
• GPU: Any Vulkan-capable GPU (skill defaults to Vulkan to avoid OpenGL flickering on Linux)
• Agent: pi, Claude Code, or any agent supporting the Agent Skills standard

License

MIT