/script

name: unity-script
description: Create, read and analyze C# scripts

> **Before calling any skill in this module:** if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via `GET /skills/recommend?includeSchema=true`) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

Triggers

• Authoring or editing C# code
• Searching across scripts
• Refactoring file layout
• Checking compile errors
• 编写或编辑 C# 代码、跨脚本搜索、重构文件布局、检查编译错误

Unity Script Skills

> **BATCH-FIRST**: Use `script_create_batch` when creating 2+ scripts. > **DESIGN-FIRST**: Before creating gameplay scripts, actively consider coupling, performance, and maintainability. In an existing project, load `../project-scout/SKILL.md` first. If the user is asking for architecture or refactoring advice, load `../architecture/SKILL.md` and then `../patterns/SKILL.md`, `../async/SKILL.md`, `../inspector/SKILL.md`, `../performance/SKILL.md`, `../script-roles/SKILL.md`, `../scene-contracts/SKILL.md`, `../testability/SKILL.md`, or `../scriptdesign/SKILL.md` as needed.

Operating Mode

• **Approval**: 只读类 skill（`script_read` / `script_list` / `script_find_in_file` / `script_get_info` / `script_get_compile_feedback`，标 `SkillMode.SemiAuto`）直接执行；本模块**没有可 grant 的写型 skill** —— 每一个写型 skill 都命中下一条的自动拦截，grant 只会再返一次 `MODE_FORBIDDEN`。
• **Auto / Bypass**: SemiAuto 与（Bypass 下的）写型 skill 直接执行。
• **本模块全部 7 个写型 skill 都是 Delete / Reload 类高危**：`script_create` / `script_create_batch` / `script_replace` / `script_append` / `script_rename` / `script_move` / `script_delete` 均标 `MayTriggerReload = true` + `RiskLevel = "high"`（落盘 .cs 必然触发 Domain Reload），`script_delete` 另标 `SkillOperation.Delete` —— 这些 skill 被 `IsForbiddenInSemi` 静态拦截，在 Approval **和** Auto 下都返 `MODE_FORBIDDEN`，**仅 Bypass 或 Allowlist 命中可执行**，不要尝试 grant 流程。

**DO NOT** (common hallucinations):

• `script_edit` / `script_update` do not exist → use `script_replace` for find-and-replace
• `script_write` does not exist → use `script_create` (new file) or `script_replace` (modify existing)
• `scriptName` parameter must NOT include `.cs` extension
• Templates only accept: MonoBehaviour, ScriptableObject, Editor, EditorWindow

**Routing**:

• To modify existing script content → `script_replace` (find/replace) or `script_append` (add lines)
• To read script → `script_read`
• To check compile errors → `script_get_compile_feedback`
• To analyze script API → use `perception` module's `script_analyze`

Skills Overview

| Single Object | Batch Version | Use Batch When | |---------------|---------------|----------------| | `script_create` | `script_create_batch` | Creating 2+ scripts |

**No batch needed**:

• `script_read` - Read script content
• `script_list` - List C# script files under a folder
• `script_get_info` - Read class name, base class, public methods/fields
• `script_delete` - Delete script
• `script_find_in_file` - Search in scripts
• `script_append` - Append content to script
• `script_replace` - Find and replace inside one script (plain text or regex)
• `script_rename` - Rename a script file in place
• `script_move` - Move a script to another folder; a missing destination folder is created automatically
• `script_get_compile_feedback` - Check compile errors for one script after Unity finishes compiling
• `create_script()` in `scripts/unity_skills.py` now waits for Unity to come back once and refreshes compile feedback automatically after script creation.

---

Skills

script_create

Create a C# script from template.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `scriptName` | string | Yes | - | Script class name | | `folder` | string | No | "Assets/Scripts" | Save folder | | `template` | string | No | "MonoBehaviour" | Template type | | `namespaceName` | string | No | null | Optional namespace | | `checkCompile` | bool | No | true | Check compilation after create | | `diagnosticLimit` | int | No | 20 | Max compile diagnostics |

**Templates**: MonoBehaviour, ScriptableObject, Editor, EditorWindow

**Returns**: `{success, status, path, jobId, className, namespaceName, designReminder, serverAvailability?}`

Poll the returned `jobId` (or call `script_get_compile_feedback`) to obtain compile diagnostics — they are not embedded in the synchronous response. `serverAvailability` carries the transient-unavailable hint when Unity is about to reload the script domain.

script_create_batch

Create multiple scripts in one call.

**Returns**: `{success, totalItems, successCount, failCount, results: [{success, path, className}], compilation?}`

Before batch creation, decide whether each script should be:

• a thin `MonoBehaviour` bridge
• a `ScriptableObject` configuration asset
• or a plain C# domain/service class generated from a custom template

unity_skills.call_skill("script_create_batch", items=[
    {"scriptName": "PlayerController", "folder": "Assets/Scripts/Player", "template": "MonoBehaviour"},
    {"scriptName": "EnemyAI", "folder": "Assets/Scripts/Enemy", "template": "MonoBehaviour"},
    {"scriptName": "GameSettings", "folder": "Assets/Scripts/Data", "template": "ScriptableObject"}
])

script_read

Read script content.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scriptPath` | string | Yes | Script asset path |

**Returns**: `{path, lines, content}`

script_delete

Delete a script.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scriptPath` | string | Yes | Script to delete |

**Returns**: `{success, status, deleted, jobId, serverAvailability?}`

script_find_in_file

Search for patterns in scripts.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `pattern` | string | Yes | - | Search pattern | |