Unity Script Agent Skill

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）直接执行；写型 skill（script_create / script_create_batch / script_replace / script_append / script_rename / script_move / script_delete，默认 SkillMode.FullAuto）需用户 grant，grant 后服务端一步执行返结果。
• Auto / Bypass: 直接执行。
• 本模块含 Delete / Reload 类高危 skill：script_create / script_create_batch / script_replace / script_append / script_delete 会触发 Domain Reload（且多标 RiskLevel=high），script_delete 同时是 Delete 操作 —— 这些 skill 在 Approval / Auto 下被 IsForbiddenInSemi 自动拦截，仅 Bypass 或 Allowlist 命中可执行。

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_delete - Delete script
• script_find_in_file - Search in scripts
• script_append - Append content to script
• 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 |

| folder | string | No | "Assets" | Search folder |

| isRegex | bool | No | false | Use regex |

| limit | int | No | 50 | Max results |

Returns: {pattern, matchCount, matches: [{file, line, content}]}

script_append

Append content to a script.

| Parameter | Type | Required | Default | Description |

|-----------|------|----------|---------|-------------|

| scriptPath | string | Yes | - | Script path |

| content | string | Yes | - | Content to append |

| atLine | int | No | end | Line number to insert at |

| checkCompile | bool | No | true | Check compilation after append |

| diagnosticLimit | int | No | 20 | Max compile diagnostics |

script_get_compile_feedback

Get compile diagnostics related to one script.

| Parameter | Type | Required | Default | Description |

|-----------|------|----------|---------|-------------|

| scriptPath | string | Yes | - | Script path |

| limit | int | No | 20 | Max diagnostics |

Example: Efficient Script Setup

import unity_skills

# BAD: 3 API calls + 3 Domain Reloads
unity_skills.call_skill("script_create", scriptName="PlayerController", folder="Assets/Scripts/Player")
# Wait for Domain Reload...
unity_skills.call_skill("script_create", scriptName="EnemyAI", folder="Assets/Scripts/Enemy")
# Wait for Domain Reload...
unity_skills.call_skill("script_create", scriptName="GameManager", folder="Assets/Scripts/Core")
# Wait for Domain Reload...

# GOOD: 1 API call + 1 Domain Reload
unity_skills.call_skill("script_create_batch", items=[
    {"scriptName": "PlayerController", "folder": "Assets/Scripts/Player"},
    {"scriptName": "EnemyAI", "folder": "Assets/Scripts/Enemy"},
    {"scriptName": "GameManager", "folder": "Assets/Scripts/Core"}
])
# Wait for Domain Reload once...

Important: Domain Reload And Compile Feedback

After creating or editing scripts, Unity triggers a Domain Reload (recompilation). Use the returned compilation field first. If isCompiling=true, wait for Unity to finish and then call script_get_compile_feedback.

import time

result = unity_skills.call_skill("script_create", scriptName="MyScript")
time.sleep(5)  # Wait for Unity to recompile if result["compilation"]["isCompiling"] is true
feedback = unity_skills.call_skill("script_get_compile_feedback", scriptPath=result["path"])
unity_skills.call_skill("component_add", name="Player", componentType="MyScript")

Best Practices

• Use meaningful script names matching class name
• Organize scripts in logical folders
• Before creating gameplay code, decide the class role first: MonoBehaviour, ScriptableObject, or plain C# helper/service
• Actively reduce coupling: prefer explicit dependencies, small responsibilities, and event-driven notifications over hidden globals
• Actively consider performance: avoid unnecessary Update, repeated Find, reflection in hot paths, and avoidable allocations
• Actively consider maintainability: clear naming, explicit ownership, Inspector-friendly fields, and simple module boundaries
• Avoid giant boilerplate/template dumps. Start from the smallest structure that solves the current need
• Do not default to UniTask or a global event bus unless the project context justifies them
• Avoid cryptic abbreviations in class, field, and method names unless they are already a project convention

10. Use templates for correct base class

11. Wait for compilation after creating scripts

12. After script edits, call script_get_compile_feedback and fix reported errors

13. Use regex search for complex patterns

14. Use batch creation to minimize Domain Reloads

Additional Skills

script_replace

Find and replace content in a script file.

| Parameter | Type | Required | Default | Description |

|-----------|------|----------|---------|-------------|

| scriptPath | string | Yes | - | Script asset path |

| find | string | Yes | - | Text or pattern to find |

| replace | string | Yes | - | Replacement text |

| isRegex | bool | No | false | Use regex matching |

| checkCompile | bool | No | true | Check compilation after replace |

| diagnosticLimit | int | No | 20 | Max compile diagnostics |

Returns: { success, status, path, jobId, replacements, serverAvailability? }

script_list

List C# script files in the project.

| Parameter | Type | Required | Default | Description |

|-----------|------|----------|---------|-------------|

| folder | string | No | "Assets" | Folder to search in |

| filter | string | No | null | Filter string for path matching |

| limit | int | No | 100 | Max results |

Returns: { count, scripts: [{ path, name }] }

script_get_info

Get script info (class name, base class, methods).

| Parameter | Type | Required | Default | Description |

|-----------|------|----------|---------|-------------|

| scriptPath | string | Yes | - | Script asset path |

Returns: { path, className, baseClass, namespaceName, isMonoBehaviour, publicMethods, publicFields }

script_rename

Rename a script file.

| Parameter | Type | Required | Default | Description |

|-----------|------|----------|---------|-------------|

| scriptPath | string | Yes | - | Script asset path |

| newName | string | Yes | - | New script name (without extension) |

| checkCompile | bool | No | true | Check compilation after rename |

| diagnosticLimit | int | No | 20 | Max compile diagnostics |

Returns: { success, status, path, jobId, oldPath, newName, serverAvailability? }

script_move

Move a script to a new folder.

| Parameter | Type | Required | Default | Description |

|-----------|------|----------|---------|-------------|

| scriptPath | string | Yes | - | Script asset path |

| newFolder | string | Yes | - | Destination folder. Must already exist. |

| checkCompile | bool | No | true | Check compilation after move |

| diagnosticLimit | int | No | 20 | Max compile diagnostics |

Returns: { success, status, path, jobId, oldPath, newPath, serverAvailability? }

Exact Signatures

Exact names, parameters, defaults, and returns are defined by GET /skills/schema or unity_skills.get_skill_schema(), not by this file.