Unity CI Kit

SKILL.md

---
name: unity-ci-kit
description: Unity CI pipeline toolkit. Provides ci_agent.py Python CLI and CiRunner.cs Unity Editor script for fully automated Unity batchmode builds, compile checks, and structured error parsing. Use this skill to set up automated CI for Unity projects, run batchmode compilation, create reusable build pipelines, or migrate existing CI scripts to a config-driven cross-project framework.
agent_created: true
---

# Unity CI Kit

## Purpose

A drop-in CI toolkit for Unity projects that enables fully automated build-test-validate pipelines.
The Python agent (`ci_agent.py`) handles Unity batchmode invocation and result parsing;
the C# runner (`CiRunner.cs`) provides a reusable step framework inside Unity Editor.
Together they eliminate the need for manual Unity Editor interaction during development iterations.

## When to Use

Trigger this skill when:
- User asks to "set up CI for Unity" or "automate Unity builds"
- User wants to run Unity batchmode compilation from the command line
- User needs to migrate a hardcoded CI script to a reusable, config-driven kit
- User mentions `ci_agent.py`, `ci_config.json`, or `CiRunner.cs` in the context of Unity automation
- User is setting up a new Unity project and wants a proven CI pipeline from day one

Do NOT use this skill for non-Unity projects, or for simple one-off shell scripts that don't need a reusable framework.

## Workflow

### Step 1: Initialize the Project

Run `ci_agent.py init` from the Unity project root. This creates `ci_config.json` with defaults.
Edit the config to set:

- `unity_version` — e.g. `"2022.3.62f3c1"` (matches ProjectVersion.txt)
- `unity_path` — leave empty for auto-discovery, or set absolute path
- `execute_method` — the Unity static method to invoke, e.g. `"StarVanguard.Editor.AutoCI.RunCI"` or `"UnityCI.Editor.CiRunner.RunCI"`

### Step 2: Install the Unity-side Runner

Copy `templates/CiRunner.cs` (from this skill's `templates/` directory) into the project's `Assets/Editor/` (or `Assets/_Project/Scripts/Editor/`).

Edit the `RunPipeline()` method to insert project-specific build steps. Each step uses the `Step(string name, Func<bool> action)` helper:

```csharp
private static bool RunPipeline()
{
    bool ok = true;
    ok &= Step("Create Assets",  () => { AssetBuilder.Run();   return true; });
    ok &= Step("Run Validation", () => { TestRunner.RunAll();   return testsPassed; });
    ok &= Step("Apply Font",     () => { FontSetup.Apply();     return true; });
    AssetDatabase.SaveAssets();
    return ok;
}
```

The helper automatically wraps each step in try-catch and logs `[AutoCI] STEP: name => OK/FAIL`.
The Python agent parses these log lines to produce structured JSON output.

### Step 3: Verify Environment

Run `python ci_agent.py check` to verify:
- Python version is compatible
- `ci_config.json` is present and valid
- Unity executable is found at the configured path or auto-discovered
- The project contains an `Assets/` directory

### Step 4: Run CI

```bash
python ci_agent.py build     # Full pipeline (batchmode + executeMethod + parse)
python ci_agent.py compile   # Compile-only (fast check)
python ci_agent.py status    # Read last build result JSON
```

The `build` command:
1. Launches Unity in batch mode (`-batchmode -quit -nographics`)
2. Executes the configured `execute_method`
3. Reads `ci_output.log` and parses CS errors/warnings
4. Writes structured JSON to `ci_result.json`
5. Prints a summary to stdout

### Step 5: Integrate with AI Workflow

The structured JSON output from `ci_result.json` is designed for AI consumption:

```json
{
  "timestamp": "2026-06-30T08:30:00",
  "build_ok": true,
  "errors": [],
  "error_count": 0,
  "warnings": [...],
  "warning_count": 3,
  "ci_pass": true,
  "log_file": "ci_output.log"
}
```

AI agents can:
1. Write code changes
2. Run `python ci_agent.py compile` to verify compilation
3. If errors exist, parse `ci_result.json` → fix → repeat
4. Once clean, run `python ci_agent.py build` for full validation
5. Commit and push when all passes

## File Layout

```
project-root/
├── ci_config.json          # Created by `ci_agent.py init`
├── ci_output.log           # Generated by Unity batchmode
├── ci_result.json          # Generated by `ci_agent.py build`
├── ci_agent.py             # Copied from skill's scripts/ directory
└── Assets/
    └── Editor/
        └── CiRunner.cs     # Copied from skill's templates/ directory
```

## Bundled Resources

### scripts/ci_agent.py
The main Python CLI. Copy this to the project root. Run `python ci_agent.py` for usage.
Commands: `init`, `check`, `build`, `compile`, `status`.

### templates/ci_config.json
Minimal config template. Fields: `unity_version`, `unity_path`, `execute_method`, `timeout_seconds`, `log_file`, `result_file`.

### templates/CiRunner.cs
Generic Unity Editor script. Provides `Step()` framework and `RunCI()` entry point.
Namespace: `UnityCI.Editor`. Method: `public static void RunCI()`.

### references/setup_guide.md
Step-by-step setup instructions for new projects.