Skip to main content
skill CX Codex

scenario-unreal-expert — Claude Code skill: install and features

scenario-unreal-expert controls Unreal Engine 5.8 on macOS via Editor Python, Epic Unreal MCP, and headless commandlets. Helps automate scenes, builds, and asset pipelines.

MIT 480 installs ★ 3,964 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add scenario-labs/skills --skill scenario-unreal-expert -a claude-code
Open on GitHub

What scenario-unreal-expert does

This skill guides coding agents through driving Unreal Engine 5.8 on Apple Silicon Mac. It routes tasks across four execution routes: the official Epic Unreal MCP plugin for scene and actor updates, in-editor Python via ue_remote.py, headless UnrealEditor-Cmd jobs for CI or batch imports, and single-shot full editor boots using -ExecutePythonScript.

Actions in the running editor happen inside named transactions with explicit asset saves. Running a headless commandlet against a project already loaded in the editor will fail because the editor holds a write lock on the files. For the same reason, MCP tool calls run strictly one by one on the game thread.

What it helps with

  • run Editor Python scripts inside an active Unreal Engine 5.8 instance
  • execute headless batch imports and audits using UnrealEditor-Cmd
  • configure Epic Unreal MCP connections via local port 8000
  • prevent asset write-lock conflicts between commandlets and the editor GUI

Example prompts for the agent

  • Run a headless Python audit on the scratch project and wait for the Asset Registry
  • Execute this actor update in the open editor using ue_remote.py within a single transaction
  • Capture a screenshot using the latent editor boot mode without starting the GUI

How to install scenario-unreal-expert

1Skills CLI (Vercel)

npx skills add scenario-labs/skills --skill scenario-unreal-expert -a claude-code

2Manually: put the files in place

~/.claude/skills/scenario-unreal-expert/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/scenario-unreal-expert/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about scenario-unreal-expert

How to install scenario-unreal-expert in Claude Code?

Run npx skills add scenario-labs/skills --skill scenario-unreal-expert -a claude-code in your terminal. The configuration installs to ~/.claude/skills/scenario-unreal-expert/SKILL.md.

What does scenario-unreal-expert do?

It establishes an agent execution protocol for Unreal Engine 5.8 on macOS, routing automation across MCP, commandlets, and in-editor Python.

Can headless commandlets run while the Unreal editor is open?

They can read data, but any headless commandlet attempting to save will fail because the active editor instance holds an exclusive write lock.

Source text

SKILL.md · MIT
---
name: scenario-unreal-expert
description: "Use when an agent drives Unreal Engine 5.8 on a Mac for any task: Editor Python (the unreal module), headless UnrealEditor-Cmd -run=pythonscript jobs, Epic's Unreal MCP server, the Remote Control API, console commands and cvars; when a script breaks on 5.8 (EditorLevelLibrary, Remote Control calls refused, Substrate materials black, MRQ presets); when a level, material, shot or build must be judged by numbers and a screenshot before it is called done; or when a brief must go to the right scenario-unreal-* specialist."
license: MIT
---

# Unreal expert (technical director and agent protocol)

Expert Unreal work is a loop run against numbers: set the budget, build one stage, measure it, look
at it, fix it, then advance. An agent without a mouse gets there by choosing the right channel for
each action, working like the Details panel (one transaction, explicit saves), and never trusting
its own eyes alone. This skill is the protocol, the shared toolkit in [`scripts/`](scripts/), and
the map to the team. Target: UE 5.8 on macOS Apple Silicon. If a sibling skill named here is missing
from your available skills, load it with `skill_get` (Scenario MCP) or ask the user to install it
(https://github.com/scenario-labs/skills#install); unattended, proceed from tool schemas and flag
the gap.

**Status (2026-09-24):** UE 5.8 is not installed. Every in-engine call in `scripts/` and
`references/` is **not yet run in Unreal**. The pure-Python parts ran offline and pass (eight test
files, 314 checks on Python 3.14, 311 on 3.9). First action once the engine is installed:
`tests/code/unreal-expert/run_all.sh --live` with `UE_TEST_PROJECT` set to a scratch project, then
[`references/ue-5.8-traps.md`](references/ue-5.8-traps.md) section 7.

## 1. Execution channels

| Channel                                                                                                                                  | Use for                                                                                                                              | Rules                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Epic Unreal MCP** (plugin `ModelContextProtocol`, Experimental), your MCP client via `.mcp.json`                                       | structured edits covered by shipped toolsets (actors, scene, material instances, Sequencer, PCG, UMG, animation), in the open editor | Enable Unreal MCP and All Toolsets; if "connected but can do nothing", add Editor Toolset, which Epic's webinar says the docs omit (Sam Deiter, k0tgmrBuIJc [00:18:13]). Start with `-ModelContextProtocolStartServer -ModelContextProtocolPort=8000` or `ModelContextProtocol.StartServer`; `ModelContextProtocol.GenerateClientConfig ClaudeCode` writes `.mcp.json`; editor first, agent second. Calls run serially on the game thread: never overlap them. `describe_toolset` only for the toolset you need now: Niagara's is "almost a quarter of a million" (k0tgmrBuIJc [00:46:04]). Loopback, no auth. |
| **Editor Python in the running editor** ([`ue_remote.PythonRemote`](scripts/ue_remote.py), or a custom Python toolset on the MCP server) | loops, audits, anything toolsets lack, screenshots                                                                                   | Enable Python Remote Execution (Project Settings > Plugins > Python). Full `unreal` API; the editor ticks between calls. One call = one named transaction that reports what it did.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **Headless commandlet** ([`ue_run.run_python`](scripts/ue_run.py), `UnrealEditor-Cmd <uproject> -run=pythonscript`)                      | audits, imports, batch edits, validation, CI, when no editor has the project open                                                    | No level loaded (`map=` loads one), fewer modules, no rendering. The boot waits for the Asset Registry (`get_asset_registry().wait_for_completion()`, 5.8 batch example); a job passes only on its boot's job-id `UE_RESULT` line, never on the exit code. A commandlet that saves must not touch a project an open editor has loaded: the editor holds a write lock (Jamie Dale, 0guOMTiwmhk [01:17:18]).                                                                                                                                                                                                     |
| **Full editor, one shot** (`mode="editor"`: `-ExecutePythonScript`; `mode="latent"`: ticking boot that quits after)                      | jobs needing full modules; latent: screenshots and renders without a running editor                                                  | `-ExecutePythonScript` shuts down right after the script, so nothing ticks; `ue_run` adds `-ScriptErrorsAreFatal` (5.5) so a failing script fails the process. Latent jobs are generators: `yield` = one tick.                                                                                                                                                                                                                                                                                                                                                                                                 |
| **Remote Control API** (`ue_remote.RemoteControl`, 127.0.0.1:30010)                                                                      | batched property writes on known objects, live presets, `-game` builds                                                               | Off until `WebControl.StartServer`. **5.8 disables remote UFUNCTION calls by default** with an allow list (5.8 release notes). C++ names, `WRITE_TRANSACTION_ACCESS` for undo, public EditAnywhere properties only.                                                                                                                                                                                                                                                                                                                                                                                            |
| **Console and cvars**                                                                                                                    | stats, view modes, quality switches, `HighResShot`                                                                                   | From Python `unreal.SystemLibrary.execute_console_command(world, cmd)` [verify]; at launch `-DPCVars=` (before init, overrides read-only cvars; Profiling with Purpose, C-AjCqjKRSs [00:14:13]), not `-ExecCmds`. Restore what you change.                                                                                                                                                                                                                                                                                                                                                                     |
| **Commandlets and UAT** (`ue_run.run_commandlet`, `run_uat`)                                                                             | `DataValidation`, `ResavePackages -fixupredirects`, `WorldPartitionBuilderCommandlet`, `BuildCookRun`                                | Headless; parse the log (`ue_run.scan_log`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

**Capability matrix** (from the 5.8 docs and talks; `tests/code/unreal-expert/jobs/job_00_probe.py`
confirms or corrects each row):

| Action                                         | MCP                                            | Python, running editor                                                                        | Headless commandlet                            | Remote Control                 |
| ---------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------ |
| read and edit actors, assets, properties       | toolsets                                       | yes                                                                                           | yes (load the level first)                     | public EditAnywhere properties |
| material instances and parameters              | `MaterialInstanceTools`                        | yes                                                                                           | yes                                            | properties only                |
| material graphs                                | toolset (large schema)                         | `MaterialEditingLibrary`, partial: some pins unexposed (Matt Oztalay, m6mJ9r7ytks [00:13:39]) | same                                           | no                             |
| Blueprint graphs, AnimGraph [verify]           | Blueprint toolset [verify scope]               | 5.8 `BlueprintGraphEditor` [verify scope]                                                     | same                                           | no                             |
| Niagara emitters and modules                   | toolset, huge schema                           | no emitter or module editing                                                                  | no                                             | user parameters                |
| PCG graphs                                     | PCG toolset, primitives, fire-and-forget calls | graph API [verify]                                                                            | yes                                            | no                             |
| screenshots, MRG stills, PIE                   | via Python toolset                             | yes                                                                                           | no (use `mode="latent"` or `-game` render CLI) | no                             |
| landscape sculpt, foliage paint, Fracture Mode | no                                             | no                                                                                            | no                                             | no                             |
| cook, package, validate                        | no                                             | not the cook (in-editor cook removed in 5.9)                                                  | yes, UAT                                       | no                             |

**Graph editors and viewport tools, substitutes:** Blueprints: logic in C++ (code project, Xcode)
with data-only Blueprints; template Blueprints duplicated and their defaults set; never 150 Delay
nodes or unjustified Event Tick (k0tgmrBuIJc [00:56:45], [00:57:19]). Materials: instances of
approved masters; node graphs, never a whole-HLSL Custom node unless required (k0tgmrBuIJc
[00:39:27]). Niagara: duplicate template systems, set user parameters. PCG: compose Epic's
primitives and example graphs (lDf_y-YPELo [00:05:20]). Control Rig: its "Copy Python Script".
Sculpting, painting, fracturing: heightmap import, PCG, Dataflow graphs, or a human step, said
plainly.

**Write locks and source control:** `ue_run` lists UnrealEditor processes holding the project
(`ps`); pass `lock_check="refuse"` for jobs that save. 5.8's PythonScript commandlet enables source
control before the script, so saves can check out [verify with Perforce]; `ResavePackages` needs
`-autocheckout` (redirectors doc). Stop when a file you must edit is not checked out (Bardoux,
MjjkWH0eT3U [00:55:27]). OFPA changelists are submitted from inside the editor: partial submits
leave dangling references (World Partition doc). Content a builder regenerates, such as PCG
partition actors, stays out of changelists (TbNZ4GKaTow [00:26:23]).

## 2. The expert loop

**Name the engine call behind every toolkit call**, in plans as in reports: a reader without
`scripts/` must be able to check each step. Write
[`ue_review.screenshot(p, 1920, 1080)`](scripts/ue_review.py)
(`AutomationLibrary.take_high_res_screenshot`, fallback `HighResShot 1920x1080`), cvars and console
commands literally, and close with **Verified** (what ran, with the number, log line or frame that
proves it) and **Assumed** (not run in Unreal, [verify] names, defaults taken). Mapping and
template: [`references/toolkit-map.md`](references/toolkit-map.md).

1. **Brief in numbers.** Platform and device class; frame budget in ms per thread and GPU (16.67 at
   60 fps, 33.3 at 30; Ari Arnbjörnsson, GuIav71867E [00:03:53]); output resolution and upscaler;
   scale (world size, actors, NPCs); gameplay or cinematic; references. When silent, take the domain
   skill's default and write it down.
2. **Preflight.** [`ue_env.preflight()`](scripts/ue_env.py) (chip, macOS, Xcode),
   `ue_env.find_project()` (plugins, path spaces), and the project settings that change the plan:
   `r.Substrate`, Lumen, VSM, Nanite, hardware ray tracing (`ue_env.read_ini_value`, or the probe).
   Upgraded projects keep old renderer settings [added].
3. **Build one stage** with small idempotent scripts: get-or-create by path, mark what you create,
   one transaction per logical operation, explicit saves.
4. **Measure.** [`ue_audit.verdict`](scripts/ue_audit.py) for content; `stat unit` to classify
   (Frame, Game, Draw, GPU, RHIT), then Insights (lean capture for "are we on budget", rich with
   `-statnamedevents` for "why", about 20% overhead, C-AjCqjKRSs [00:11:27]);
   [`ue_stat.budget_check`](scripts/ue_stat.py) on CSV profiler or TraceQuery JSONL. Profile a
   cooked Development or Test build on target hardware; this Mac is a proxy for a console. Measure
   before any rewrite (VMZftEVDuCE [00:16:33]); when Insights cannot explain a hitch, add a sampling
   profiler (C-AjCqjKRSs [00:17:30]).
5. **Look AND check.** Screenshots from fixed camera bookmarks or an MRG still, opened with the
   image reader, plus `ue_review.image_checks`: Epic's lighting agent approved an all-white frame
   (lDf_y-YPELo [00:17:29]). `review_images` gives flags and a contact sheet in one call. Judge with
   the domain skill's `references/critique.md`. After a render, look for 5.8's on-screen
   exposure-range warning; an MRG frame that differs from the viewport: suspect Game Overrides first
   (fVg5ihB8Wdc [00:03:33]).
6. **Fix before advancing**, one change at a time, with `ue_review.compare` for before and after
   parity from the same views.
7. **Deliver with evidence** in that format: saved assets and levels, audit and stat JSON, the
   frames you looked at with their checks, the Verified and Assumed lists.

Never report a level, material, shot or build as done without numbers and a frame you looked at.

## 3. Persona pipelines

| Brief                      | Chain                                                                                                                                       | Deliverable                            |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| Open world or level        | scenario-unreal-world-building, scenario-unreal-materials (landscape, RVT), scenario-unreal-lighting-rendering, scenario-unreal-performance | streamed level, HLODs, budget report   |
| Material kit               | scenario-unreal-materials, then scenario-unreal-lighting-rendering (test bench), scenario-unreal-performance (shader cost)                  | masters, instances, permutation audit  |
| Lit interior or hero still | scenario-unreal-lighting-rendering (scenario-unreal-materials for emissives), scenario-unreal-cinematics for MRG output                     | gameplay lighting at budget, EXR still |
| Gameplay prototype         | scenario-unreal-gameplay, scenario-unreal-animation, scenario-unreal-vfx for abilities, scenario-unreal-performance                         | playable map, automation tests         |
| Character from Maya        | scenario-unreal-pipeline-automation (import), scenario-unreal-animation, scenario-unreal-gameplay                                           | retargeted, locomotion-ready character |
| Trailer                    | scenario-unreal-cinematics (scenario-unreal-animation, scenario-unreal-lighting-rendering)                                                  | Sequencer shots, reviewed renders      |
| VFX or destruction         | scenario-unreal-vfx, scenario-unreal-performance                                                                                            | systems within budget                  |
| Batch import and build     | scenario-unreal-pipeline-automation, scenario-unreal-performance (packaging)                                                                | report, validated package              |
| Frame-rate rescue          | scenario-unreal-performance, routing fixes to owners                                                                                        | proof capture, parity frames           |

**Handoff contract:** saved assets in a named folder, the `ue_audit.verdict` for the receiver's
profile with no error, stat or trace numbers when performance matters, the frames the sender looked
at with their `image_checks`, each toolkit call with its engine call, and the Verified and Assumed
lists. Units are centimeters, Z-up [added]. Sister teams: scenario-maya-expert (1 unit = 1 cm, Y-up
in Maya), scenario-zbrush-expert, scenario-blender-expert (FBX through scenario-blender-export);
scenario-3d for generated meshes to finish.

## 4. Shared toolkit (`scripts/`, in-engine parts not yet run in Unreal)

Import: `import sys; sys.path.insert(0, "<this skill>/scripts")`. `PythonRemote.call` adds that
folder in the editor for one call.

- `ue_env.py`: `find_engine(version=None)` (editor, editor_cmd, uat, version; `UE_ROOT` override),
  `find_project(path)`, `preflight()`, `plan_plugins` / `enable_plugins` (timestamped backup),
  `read_ini_value`, `xcode_status`.
- `ue_run.py`:
  `run_python(uproject, script, args=None, map=None, timeout=1800, mode="commandlet"|"editor"|"latent", strict=False, lock_check="warn")`
  returns the `UE_RESULT` envelope plus log scan and `warnings`; job side `result(obj)`, `args()`,
  `in_commandlet()`, `to_jsonable()`, `wait_for_registry()`; `run_commandlet(uproject, name, args)`,
  `run_uat`, `build_buildcookrun`, `launch_editor(mcp_port=)`, `stop_editor`, `editor_processes`,
  `scan_log`, `parse_ue_result`.
- `ue_remote.py`:
  `RemoteControl(host, port).info/describe/get_property/set_property/call/batch/search_assets/console`,
  errors carry fix hints; `PythonRemote().open/exec/call/close`; `McpHttp().health()` (reachability,
  tool search); `loopback_only(port)`, `pie_path`, `cdo_path`, `python_cdo_path`.
- `ue_review.py`: in editor `set_camera`, `screenshot`, `wait_screenshot`, `screenshot_views`,
  `camera_views_from_actors`, `render_still` (MRG or MRQ preset, own queue), `wait_render`; offline
  `image_checks` (histogram, clipped, crushed, EV-like, center vs surround, all_white, all_black,
  uniform, alpha), `image_verdict`, `compare`, `contact_sheet`, `review_images`, `wait_for_file`,
  `build_render_command`.
- `ue_audit.py`: in editor `audit_assets(paths, rules, profile)`, `collect_facts`; anywhere
  `evaluate`, `build_report`, `verdict(report, "game"|"cinematic"|"mobile"|"prototype")`; Epic
  prefixes, texture size and compression, Nanite, collision, LODs, slots, instance parents, Custom
  HLSL, After-DOF translucency, redirectors.
- `ue_stat.py`: `parse_stat_unit`, `parse_csv_profile` + `csv_frames`, `parse_jsonl` +
  `sniff_schema` + `trace_frames` + `timer_totals`, `budget_check(frames, target_ms)`, `bound_by`,
  `summarize`.

Domain skills add `scripts/ue_<domain>.py`; they never copy these. The engine call behind each
function: `references/toolkit-map.md`.

## 5. Top 5.8 traps (full list: `references/ue-5.8-traps.md`)

- **`EditorLevelLibrary` and `EditorAssetLibrary` are the old API**: `EditorActorSubsystem`,
  `LevelEditorSubsystem`, `UnrealEditorSubsystem`, `EditorAssetSubsystem` via
  `unreal.get_editor_subsystem`. Epic's own 5.8 samples still use the old names. `load_level`
  discards unsaved changes; `delete_asset` force-deletes and may clear undo; `destination_name` is
  ignored under Interchange.
- **Substrate defaults depend on project age**: on for projects created in 5.7+, legacy for upgraded
  ones until opted in; Substrate materials render black with it off; no Metallic pin; Mac listed
  with known issues. Read `r.Substrate` before authoring.
- **Mac feature support**: Apple Silicon only; Nanite and VSM Beta on M2+; Lumen HWRT and MegaLights
  Experimental on M2+; path tracing via Metal, macOS 26.4+. Xcode: Epic lists 26.0 minimum, 26.1.1
  recommended, 26.4 incompatible; this Mac has 26.6, unlisted: verify a C++ build.
- **MRG renames**: Movie Render Graph Production Ready, new features graph-only, MRQ presets legacy,
  queue default "Basic"; `MoviePipelinePrimaryConfig` (not Master); `set_graph_preset()` for graph
  jobs; end frames exclusive; H.264 node Windows only.
- **Remote Control defaults**: server off until started, remote UFUNCTION calls refused by default
  in 5.8, 127.0.0.1 only; opening `DefaultBindAddress` to the LAN likely exposes the unauthenticated
  MCP server too [added inference].

## 6. macOS specifics

- Launcher installs land in `/Users/Shared/Epic Games/UE_5.8/`; the editor is
  `Engine/Binaries/Mac/UnrealEditor.app/Contents/MacOS/UnrealEditor`; the `-Cmd` location is
  [verify] and `find_engine` falls back to the editor with `-run=`; UAT is `RunUAT.sh`; cook
  platform `Mac`.
- Keep the Unreal project in a path without spaces (Allar style guide) [verify impact]; the toolkit
  stages jobs in a space-free folder anyway.
- Metal only: DX11, DX12 and Vulkan tips do not apply; RenderDoc does not support Metal, use Xcode's
  Metal debugger [added]; Metal System Trace shows shader compiles and thermal throttling that
  invalidate captures (ufPtQEtk-RQ [00:14:06], [00:18:17]). Insights memory callstacks are not
  listed for Mac. Outside Insights, the Mac sampling profiler is Instruments Time Profiler [added].
- Docs show Ctrl shortcuts and Windows paths: translate to Cmd [verify] and POSIX paths. A MacBook
  has no numpad: rebind the Gameplay Debugger's numpad category keys (tranek GAS guide 6.2, in the
  version deltas).
- Never kill an editor you did not launch; save before stopping one you did.

## References

- `references/ue-5.8-traps.md`: every 5.8 change that breaks remembered code or old tutorials, with
  sources, and the first-run checklist. Load before writing code from memory.
- `references/toolkit-map.md`: the engine call, command or cvar behind every toolkit function, and
  the report format (engine call per step, Verified and Assumed).
- [`references/python-reliability.md`](references/python-reliability.md): `unreal` module idioms and
  procedures (subsystems, paths, transactions, saving, get-or-create, marking what you create, the
  write lock and source control, latent work, imports, raw screenshot loop).
- [`references/sources.md`](references/sources.md): every source, with credentials, URLs and best
  timestamps.

© scenario-labs · MIT · scenario-labs/skills

Similar skills

All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set172

The whole set →
scenario-godot-expert scenario-godot-expert drives Godot 4.7.2 via headless scripts, GUT testing, and offscreen frame captures. Designed for autonomous agents running builds, checks, and hardware profiling. CX Codex +1 498installs scenario-unreal-animation scenario-unreal-animation guides Unreal Engine 5 technical animation workflows, covering IK retargeting, Motion Matching, root motion, and AnimBP performance tuning. CX Codex +1 485installs scenario-unreal-lighting-rendering scenario-unreal-lighting-rendering is a Claude Code skill for lighting Unreal Engine 5.8 scenes with physical lighting, Lumen GI, and MegaLights. Camera calibration and proxy checks help address noise, light leaks, and dark interiors. CX Codex +1 481installs scenario-unreal-world-building scenario-unreal-world-building — a skill for Unreal Engine 5: guidance on level and open-world building — World Partition, OFPA, Data Layers, landscape, procedural generation (PCG), Nanite, streaming. CX Codex +1 481installs scenario-unreal-materials scenario-unreal-materials — a skill for Unreal Engine 5 materials and textures: master materials, instances, Substrate, texture compression, shader cost. Activates when tuning permutations, texture memory budgets, glass lighting, or decals. CX Codex +1 478installs scenario-unreal-performance scenario-unreal-performance — a performance engineering skill for Unreal Engine 5.8 projects facing frame drops, thread bottlenecks, or GPU hitches. Breaks down frame budgets into stage milliseconds. CX Codex +1 475installs scenario-unreal-cinematics The scenario-unreal-cinematics skill guides cinematic work in Unreal Engine 5.8, from Sequencer shot planning to EXR rendering and cut review. CX Codex +1 470installs scenario-godot-vfx The scenario-godot-vfx skill builds and troubleshoots Godot 4.7 particles and game-feel effects. Use it for explosions, projectile trails, smoke, impact effects, and hit-stop. CX Codex +1 469installs

Project sponsors

Companies that keep this analytics open