UnityLaparoscopicSceneSimulator/.opencode/skills/unity-mcp-orchestrator/SKILL.md

name, description

name	description
unity-mcp-orchestrator	Orchestrate Unity Editor operations through the Coplay Unity MCP bridge in this project. Use when an agent needs to inspect, create, or modify scene content, scripts, materials, prefabs, or render settings. Provides project-specific URP facts, the SurgeryBenchmark scene contract, MCP tool discipline, and the inspect → propose → verify loop.

Unity MCP Orchestrator (project-scoped)

This skill is the entry point for any agent that needs to drive the Unity Editor through MCP. It is project-specific: it encodes the facts of this repository (Unity 2022.3.25f1, URP 14.0.11, the LaparoscopicSurgeryEmulation scene, the SurgeryBenchmark/* authoring contract) so agents do not have to rediscover them on every turn.

When to load

Load this skill whenever an agent:

• Is about to call any mcp__unity__* tool (manage_gameobject, manage_components, manage_material, manage_scene, manage_prefabs, manage_graphics, manage_camera, manage_script, script_apply_edits, validate_script, read_console, refresh_unity, run_tests, manage_profiler, batch_execute, find_gameobjects, execute_menu_item, execute_code).
• Needs to reason about whether a change is bounded or destructive.
• Needs the canonical handoff format for cross-agent communication.

Project facts (do not rediscover)

• Unity version: 2022.3.25f1 (LTS).
• Render pipeline: URP 14.0.11 (not HDRP). URP assets live in Assets/Settings/URP-*.asset. Do not propose HDRP features (volumes, planar reflection probes, ray-traced reflections, exposure in physical units) — translate to URP equivalents (Volume profile + overrides, reflection probe Refresh Mode = Via Scripting, post-processing via PostProcessing Volume overrides).
• MCP bridge: com.coplaydev.unity-mcp installed from git via Packages/manifest.json. Coplay bridge runs inside the Editor.
• Active emulation scene: Assets/Scenes/LaparoscopicSurgeryEmulation.unity.
• Authored root hierarchy (do not rename, do not move camera objects):
  • SurgeryBenchmark/Shared
  • SurgeryBenchmark/Shared/AnatomySlot
  • SurgeryBenchmark/Shared/CavitySlot
  • SurgeryBenchmark/Shared/InstrumentSlot
  • SurgeryBenchmark/Scenarios/Scenario_01_CleanTissue (active by default)
  • SurgeryBenchmark/Scenarios/Scenario_02_WetSpecular (inactive)
  • SurgeryBenchmark/Scenarios/Scenario_03_LowTexture (inactive)
  • SurgeryBenchmark/Scenarios/Scenario_04_PartialOcclusion (inactive)
  • SurgeryBenchmark/Scenarios/Scenario_05_InstrumentOcclusion (inactive)
• Preserved from MainScene and not to be edited without approval: stereo rig, Blending, UI, WebRTC objects, RPC objects.
• Off-limits scripts (modify only with explicit approval): Rotator.cs, BlendShaderController.cs, DepthGetter.cs, DepthRenderPassFeature.cs, DepthTester.cs, TexturesSettings.cs, WEBRTCSender.cs, CrpcApi.cs, MinimalRpcServer.cs, plus Assets/Scripts/UDP/, Assets/Scripts/VideoChat/, Assets/Scripts/Editor/.
• Material inventory (Assets/Materials/LaparoscopicBenchmark/): CavityWall.mat, InstrumentProxy.mat, Tissue_Default.mat, Tissue_LowTexture.mat, Tissue_Wet.mat.
• Texture inventory (Assets/Textures/LaparoscopicBenchmark/): TissueMucosa.png (the canonical PBR base for tissue; check its import settings — sRGB on, normal map not needed unless authored).
• Model inventory (Assets/Models/): FabOrgans/stylizeddigestivesystem.fbx (stylized, has diffuse + normal + roughness PNGs), organs/archive.fbx (has its own Materials/, source/, textures/, archive.fbm/). The two are not interchangeable.
• Render-pipeline assets (Assets/Settings/): URP-Balanced.asset, URP-Balanced-Renderer.asset, URP-HighFidelity.asset, URP-HighFidelity-Renderer.asset, URP-Performant.asset, URP-Performant-Renderer.asset, SampleSceneProfile.asset (Volume profile), TexturesSettings.asset.
• Shaders: Assets/Shaders/RenderDepth.shader, Assets/Shaders/BlendShader.compute, Assets/Shaders/Hidden_RenderDepth.mat — leave alone unless a bounded change statement is approved.

MCP tool discipline (read-only by default)

1. Inspect first. Before any mutation, run read-only tools:
   • find_gameobjects to locate the authored roots.
   • manage_scene with action=get_hierarchy to confirm the live scene.
   • manage_graphics with action=pipeline_get_info to confirm URP is active and which URP asset is current.
   • read_console with types=["error","warning"] to see if prior edits left residue.
2. Propose a bounded change. A bounded change is: one parent container, one material variant, one camera component tweak, one Volume override, one prefab edit. Anything that touches more than one authored root, more than one URP asset, or any of the "off-limits" objects is not bounded.
3. Execute, then verify. Run the change, then re-read the affected objects and read_console for errors. Capture a screenshot through manage_camera(action="screenshot") for any visual change.

Bounded vs destructive (cheat sheet)

Change class	Examples	Required step
Read-only	find, get_hierarchy, get_material_info, pipeline_get_info, screenshot	None — just run
Bounded write	rename one GameObject, set one material property, add one Volume override, activate/deactivate one scenario root, instantiate a prefab into one slot	State the change in one sentence, then run
Destructive	delete objects, delete assets, replace URP asset, rename scenario roots, move camera/stereo rig, edit off-limits scripts, modify Packages/manifest.json	Stop. Ask for explicit approval.

Cross-tool composition patterns

• Apply one coherent change set at a time. Use batch_execute to group read-only inspection or to apply a bounded write (e.g., assign the same material to N children in one batch).
• Script edits: prefer script_apply_edits (structured) over apply_text_edits (raw). create_script, script_apply_edits, and apply_text_edits already trigger AssetDatabase.ImportAsset + RequestScriptCompilation — do not call refresh_unity immediately after, just wait for is_compiling == false on mcpforunity://editor/state and then read_console.
• Material edits: manage_material(action="set_material_shader_property") for numeric/enum, set_material_color for colors, assign_material_to_renderer for binding, create for new materials. Always pass material_path as Assets/... and re-read with get_material_info to confirm.
• Volume/profile edits: manage_graphics(action="volume_set_effect", effect="Bloom"|"Vignette"|... ) to set override parameters. For URP, the override type names are the URP package's VolumeComponent types (e.g., Bloom, Vignette, DepthOfField, MotionBlur, Tonemapping, ColorAdjustments, ChromaticAberration, FilmGrain, LensDistortion).
• Scene management: manage_scene(action="get_active"|"load"|"save"). Save only after a verified bounded change.

Handoff format (required for any multi-agent work)

After any action, emit this block (see change-reporting-handoff skill for the full template):

ROLE: <which agent>
OBSERVED: <what the inspection found>
CHANGED: <exact objects/assets/settings modified>
NOT CHANGED: <what was intentionally left alone>
RISKS: <visual / technical / performance / safety / uncertainty>
NEXT SAFE OPTIONS: <one-sentence suggestions for the next agent>

Anti-patterns to refuse

• Suggesting HDRP-specific code (ray-traced reflections, planar reflection probes, path tracer) on a URP project.
• Renaming SurgeryBenchmark/Scenarios/Scenario_0X_* roots or the slot anchors.
• Moving the stereo rig, Blending, UI, WebRTC, or RPC objects.
• Bulk-editing URP assets without a per-asset bounded change statement.
• Generating clinical/anatomical/operative instructions, claims of medical accuracy, or "do this surgery" steps. See medical-simulation-safety skill.
• Modifying Packages/manifest.json or any *.csproj / .sln file directly.
• Claiming a fix is correct without read_console + visual verification.

Quick reference: which skill pairs with which MCP tool

MCP tool	Pair with
manage_scene (get_hierarchy, get_active)	unity-hierarchy-hygiene
manage_gameobject (create, modify, delete)	unity-hierarchy-hygiene
manage_components	unity-hierarchy-hygiene + the domain skill (camera, light, material)
manage_material	pbr-materials-tissue
manage_graphics (volume_, pipeline_, skybox_, bake_)	urp-render-pipeline
manage_camera (screenshot, set_lens, create_camera)	cinematic-laparoscope-camera
manage_prefabs (create_from_gameobject, modify_contents)	unity-hierarchy-hygiene
create_script, script_apply_edits, apply_text_edits, validate_script	unity-mcp-orchestrator (this file) + medical-simulation-safety
read_console, refresh_unity, run_tests, manage_profiler	realtime-performance-budget
find_gameobjects, execute_menu_item, execute_code	unity-mcp-orchestrator (this file)