Ue5 Project Context

UE5 Project Context

The most expensive failure in agent-driven UE5 work is not bad code. It is an agent that invents a module name, assumes an engine version, and writes three files against a plugin that is not enabled. Every guess is cheap individually and compounds badly.

Fix it by externalizing project facts into one file that every skill reads before acting.

Establish the contract first

1. Discover, never assume. Engine version, engine install path, and plugin state come from commands run on this machine, not from priors. On macOS, get them via ue5-macos-apple-silicon.
2. Write the facts to .agents/ue5-project-context.md using references/context-template.md. One file, at the repo root, in version control.
3. Declare dependency direction between modules, not just names. Presentation must not drive simulation. See references/module-boundaries.md.
4. Declare units and conventions once — centimeters, seconds, degrees, and every conversion the project uses (knots, meters, kilometers). Unit drift is the top source of silent gameplay bugs in vehicle projects.
5. Record the phase bans decided by ue5-phase-bans into this file. This skill owns the row format and the fact that the section exists; it does not decide what belongs in it. Without the section, an agent that loads a good replication skill will helpfully add replication to a single-player prototype.
6. Record only commands that have actually run here, with their real absolute paths and their last-succeeded date. A runbook of plausible commands is worse than no runbook.
7. Re-verify on drift. Engine upgrade, plugin change, or a failed command invalidates the file. Stale context is the failure mode this skill creates if unmaintained; treat last_verified as load-bearing.

Load only what applies:

• references/context-template.md — the file to write.
• references/module-boundaries.md — splitting modules and keeping dependency direction one-way.

For what to ban and when it lifts, load ue5-phase-bans. This skill only stores the result.

Required answer format

When this skill fires, return:

1. Discovered facts — engine version, engine path, editor target, platform(s) and architecture, each with the command that produced it.
2. Module table — name, responsibility, and allowed dependencies (one direction).
3. Units and conventions — with conversions written out.
4. Plugin state — enabled / available-but-off / absent, per plugin the project intends to use.
5. Phase bans — banned system, reason, and the phase it may be reconsidered in.
6. Verified commands — command, purpose, last-succeeded date.
7. Unknowns — every fact you could not verify, marked unverified, with the command a human must run.

Hard rules

• Never write an engine path, version, or module name you did not read from this machine or from this repository. If discovery failed, write unverified and stop — do not fill the gap with a plausible default.
• The context file states facts and bans, not tutorials. If it grows past ~200 lines it has turned into documentation; move the prose out.
• Dependency direction is one-way. UI and VFX modules may read simulation state; simulation modules must not reference UI or VFX types. A circular dependency here is not a style issue — it makes the simulation untestable headlessly, which breaks ue5-deterministic-sim-tests.
• Config that gameplay tunes (handling, damage, dispersion, AI parameters) belongs in diffable data — Data Assets, Data Tables, CSV, or JSON — not in C++ constants and not in Blueprint graphs. State the chosen format in the context file.
• Blueprint may assemble scenes and bind UI. Any rule that decides a match outcome must not live only in a Blueprint graph; an agent cannot diff or test it.
• Phase bans outrank installed skills. If a loaded skill recommends a banned system, the ban wins and the conflict gets logged. The adjudication procedure lives in ue5-phase-bans.

Verification

The context file is correct when a fresh agent, given only the repository and no conversation history, can run the listed build and smoke commands and reach a running editor or packaged build without asking a question. Test that literally: start a new session, hand it the file, and count the questions. Any question it has to ask is a missing row.

Scope

This skill does not discover the toolchain itself (platform skills do), does not choose the gameplay architecture, and does not cover source control or CI configuration.