Unity Essentials

View saved version →

---
name: unity-bug-investigation
description: Investigate, reproduce, isolate, explain, and validate bugs in an existing Unity project. Use when the user reports exceptions, incorrect behavior, regressions, visual glitches, multiplayer desync, input problems, scene or prefab issues, build failures, performance regressions, save corruption, intermittent failures, or other Unity defects. Gather evidence before editing, distinguish symptoms from causes, test hypotheses one at a time, apply the smallest justified fix, and validate the root cause.
---

# Unity Bug Investigation

Investigate Unity defects systematically and with evidence.

Do not begin by guessing a fix from the symptom alone. Establish the baseline,
reproduce the issue when possible, collect relevant evidence, formulate a small
set of hypotheses, test them one at a time, and only then implement the smallest
justified correction.

## Surface Limits

If the current surface is Chat mode without an attached workspace, repository files, logs, screenshots, or local filesystem access, do not claim that you investigated the project. Explain that Unity Essentials can help reason from evidence the user provides, but real bug investigation requires Codex with the Unity project folder open or enough logs/files pasted into chat.

If Codex has a workspace or local files available, collect project evidence before forming a root-cause claim.

## Primary outcome

Produce one of these outcomes:

1. A confirmed root cause and validated fix.
2. A narrowed cause with strong supporting evidence and a safe next experiment.
3. A documented blocker explaining why the issue could not be reproduced or
   verified.

Do not claim a root cause unless evidence supports it.

## Relationship with project onboarding

Look for current project context before investigating:

- `Docs/AI/UnityProjectContext.md`
- `Docs/UnityProjectContext.md`
- architecture documentation
- repository instructions
- recent change notes

If the project is unfamiliar and context is missing, use the
`unity-project-onboarding` workflow first, but keep the onboarding focused on
the systems relevant to the defect.

## Knowledge routing

The skill contains:

- `foundations/`: investigation principles used across bug types
- `specializations/`: defect-area guidance
- `frameworks/`: framework-specific debugging guidance
- `references/`: templates, evidence standards, validation, and safety

Read only the guidance that materially applies.

### Mandatory foundations

For every investigation, read:

- `foundations/evidence-first-debugging.md`
- `foundations/hypothesis-management.md`
- `foundations/reproduction-and-baselines.md`

Read `foundations/instrumentation.md` when adding logs, probes, captures, or
temporary diagnostics.

Read `foundations/change-safety.md` before modifying serialized assets,
project settings, packages, scenes, prefabs, or save formats.

### Specialization routing

| Defect area | File |
|---|---|
| Exceptions and crashes | `specializations/exceptions-and-crashes.md` |
| Gameplay and state bugs | `specializations/gameplay-and-state.md` |
| Input issues | `specializations/input.md` |
| UI and localization | `specializations/ui-and-localization.md` |
| Multiplayer and desync | `specializations/multiplayer.md` |
| Physics and movement | `specializations/physics-and-movement.md` |
| Rendering, shaders, and VFX | `specializations/rendering-and-vfx.md` |
| Performance regressions | `specializations/performance.md` |
| Save and persistence issues | `specializations/save-and-persistence.md` |
| Scenes, prefabs, and serialization | `specializations/scenes-prefabs-serialization.md` |
| Build and platform failures | `specializations/build-and-platform.md` |
| Editor tooling and imports | `specializations/editor-and-imports.md` |
| Intermittent or timing bugs | `specializations/intermittent-and-timing.md` |

A defect may require more than one specialization.

### Framework routing

Read framework guidance only when the project actively uses it.

| Framework | File |
|---|---|
| Photon Fusion | `frameworks/networking/fusion.md` |
| Netcode for GameObjects | `frameworks/networking/netcode-for-gameobjects.md` |
| Mirror | `frameworks/networking/mirror.md` |
| FishNet | `frameworks/networking/fishnet.md` |
| URP | `frameworks/rendering/urp.md` |
| HDRP | `frameworks/rendering/hdrp.md` |

### Resolution priority

When guidance conflicts:

1. Explicit user constraints
2. Repository instructions
3. Evidence and reproducibility
4. Data integrity and safety
5. Framework-specific guidance
6. Defect specialization
7. Generic investigation guidance

## Core principles

1. Reproduce before fixing when practical.
2. Distinguish symptoms from causes.
3. Prefer direct evidence over intuition.
4. Record the current baseline.
5. Change one meaningful variable at a time.
6. Keep temporary diagnostics narrow and removable.
7. Avoid speculative broad refactors.
8. Preserve user data and project assets.
9. Verify the fix against the original reproduction.
10. Check for regressions around the corrected behavior.
11. Do not hide uncertainty.
12. Do not claim success from compilation alone.

## Phase 1: Convert the report into a defect contract

Extract:

- observed behavior
- expected behavior
- affected user or system
- frequency
- first known occurrence
- environment
- platform
- scene or mode
- steps already attempted
- error messages
- stack traces
- recent related changes
- severity
- data-loss or crash risk

When the report is incomplete, infer only the smallest missing context.

Do not treat a vague report such as “movement is broken” as a complete
reproduction.

## Phase 2: Establish the baseline

Before editing:

- inspect current Console messages
- identify pre-existing failing tests
- inspect the relevant current code
- inspect recent changes when Git history is available
- record relevant project and package versions
- confirm the active scene, prefab, platform, and Editor instance
- preserve representative failing data or save files when relevant

Do not clear the Console before recording useful baseline evidence.

## Phase 3: Reproduce

Attempt the narrowest reliable reproduction.

Prefer:

1. Existing automated failing test
2. Minimal EditMode or PlayMode test
3. Existing reproduction scene
4. Existing gameplay scene with exact steps
5. Target platform or device reproduction
6. Controlled synthetic reproduction

Record:

- exact steps
- observed result
- frequency
- required timing
- required data
- platform differences
- Console output
- screenshots or captures when relevant

If reproduction fails, do not immediately modify code. Compare environment,
state, configuration, and version differences first.

## Phase 4: Classify the defect

Classify the issue by likely mechanism:

- deterministic logic error
- invalid state transition
- missing reference
- lifecycle or initialization order
- serialization mismatch
- asset configuration
- timing or race condition
- physics-step mismatch
- authority or replication error
- stale cache
- data migration
- rendering pipeline incompatibility
- platform-specific API
- package or version regression
- performance saturation
- user configuration
- external service failure

Classification guides evidence gathering. It does not confirm the cause.

## Phase 5: Build hypotheses

Use `references/hypothesis-log-template.md`.

Keep a small ranked set of plausible hypotheses.

Each hypothesis must include:

- claim
- supporting evidence
- contradicting evidence
- predicted observation
- cheapest discriminating test
- current status

Prefer tests that distinguish between multiple hypotheses.

Avoid collecting large amounts of data without a decision it can inform.

## Phase 6: Inspect the execution path

Trace the relevant flow:

- entry point
- initialization
- state owner
- dependencies
- input or event source
- transformations
- side effects
- presentation
- cleanup

Identify where expected and observed behavior diverge.

Use representative code and object inspection rather than reading the whole
project.

## Phase 7: Instrument narrowly

Add temporary instrumentation only when existing evidence is insufficient.

Good instrumentation:

- records state transitions
- identifies ownership
- timestamps key events
- records object identity
- records scene and lifecycle state
- captures authority and network tick
- captures input values
- captures serialized configuration
- records exact branch decisions

Avoid:

- logs every frame without filtering
- broad exception swallowing
- permanent debug flags scattered across production code
- instrumentation that changes timing significantly
- logging secrets or personal data

Mark temporary diagnostics clearly and remove them before completion unless the
project benefits from retaining them.

## Phase 8: Test hypotheses one at a time

For each hypothesis:

1. Predict the result.
2. Run the smallest discriminating experiment.
3. Record the actual result.
4. Update the hypothesis status.
5. Do not change unrelated variables.
6. Stop pursuing contradicted hypotheses.
7. Add a new hypothesis only when evidence warrants it.

A successful workaround does not automatically prove the root cause.

## Phase 9: Confirm the root cause

A root cause is confirmed when:

- evidence explains the original symptom
- the mechanism is understood
- a targeted change removes the reproduction
- reversing or isolating the change restores the failure when practical
- nearby scenarios remain valid
- competing plausible hypotheses are sufficiently ruled out

When full confirmation is impossible, report the strongest supported cause as
likely, not confirmed.

## Phase 10: Implement the smallest justified fix

The fix should:

- address the cause, not only mask the symptom
- follow project architecture
- preserve serialized data
- avoid unrelated refactoring
- include guards only at meaningful boundaries
- include migration when data formats changed
- maintain multiplayer authority
- preserve existing public behavior unless the bug itself is that behavior

Do not add broad null checks merely to suppress an invalid state.

Do not catch and ignore exceptions to make the Console quiet.

## Phase 11: Add regression coverage

Prefer a regression test that fails before the fix and passes after it.

Choose:

- EditMode for deterministic logic
- PlayMode for lifecycle, scene, physics, and engine behavior
- multi-peer or framework tests for multiplayer
- representative old data for save migration
- platform build or device tests for environment-specific failures

If automated regression coverage is impractical, create an exact manual
verification procedure.

## Phase 12: Validate the fix

Validate:

1. Original reproduction no longer fails.
2. Relevant tests pass.
3. Unity compiles without new errors.
4. Console has no new related warnings.
5. Nearby behavior still works.
6. Repeated execution remains stable.
7. Scene reload, disable, destruction, or despawn works when relevant.
8. Target platform behavior is checked when required.

Use `references/validation-strategy.md`.

## Phase 13: Review diagnostics and diff

Before completion:

- remove temporary logging
- remove experimental branches
- remove test assets not intended for commit
- inspect all changed files
- confirm no unrelated serialization changes
- confirm no tests were disabled
- confirm no warnings were hidden
- preserve useful permanent assertions or diagnostics only when justified

## Prohibited behavior

Do not:

- guess a root cause from one symptom
- make broad refactors before reproduction
- clear evidence before recording it
- disable failing tests
- swallow exceptions
- add retries without understanding failure
- add delays to hide timing problems without evidence
- reset user data as the default fix
- regenerate scenes or prefabs wholesale
- change package versions casually
- blame Unity, a package, or a platform without evidence
- claim a multiplayer fix from one local instance
- claim a performance fix without measurement
- leave excessive logs in hot paths
- expose secrets in bug reports

## Definition of done

The investigation is complete when:

- observed and expected behavior are documented
- reproduction status is known
- baseline evidence is recorded
- relevant hypotheses were tested
- root cause is confirmed or uncertainty is explicit
- the smallest justified fix is applied when possible
- regression coverage exists or manual verification is precise
- original reproduction is retested
- nearby behavior is checked
- temporary diagnostics are removed
- changed files are reviewed
- remaining risk is documented

## Final response

Return:

### Symptom

State the observed and expected behavior.

### Root cause

State confirmed, likely, or unresolved cause with evidence.

### Fix

Summarize the smallest applied correction.

### Changed files

List important changed files and purpose.

### Validation

State exact reproduction, tests, compilation, runtime, and platform checks.

### Remaining risks

List unresolved uncertainty or follow-up checks.

Referenced files: 31

View saved version →

---
name: unity-build-validation
description: Validate that a Unity project or completed change is ready to compile, test, build, and hand off. Use when the user asks to verify a feature, confirm build readiness, check compilation, run tests, validate scenes and prefabs, inspect Console output, confirm target-platform compatibility, prepare a release candidate, or determine whether Unity work is truly complete. Establish a baseline, run the strongest available validation, distinguish pre-existing failures from introduced regressions, and report exact evidence without overstating confidence.
---

# Unity Build Validation

Validate Unity work using progressively stronger evidence.

This skill is the final verification layer for feature implementation, bug
fixes, health-check remediation, milestones, and release preparation.

Compilation is necessary but not sufficient.

A change is not fully validated merely because C# compiles.

## Surface Limits

If the current surface is Chat mode without an attached workspace, repository files, build logs, or local filesystem access, do not claim build readiness or validation. Explain that Unity Essentials can help interpret pasted build output, but real build validation requires Codex with the Unity project folder open, a connected Unity Editor, CI output, or supplied build logs.

If Codex has a workspace or local files available, validate with the strongest available evidence and clearly state any missing Unity Editor, test, platform, or device coverage.

## Primary outcome

Produce an exact validation result that answers:

- Did Unity compile?
- Were new Console errors introduced?
- Which tests ran and what passed?
- Are required scenes configured?
- Are prefabs and serialized references valid?
- Does the target build succeed?
- Was runtime behavior exercised?
- Were platform-specific checks completed?
- What remains unverified?
- Is the result ready, conditionally ready, blocked, or not validated?

## Relationship with other skills

This skill may be used after:

- `unity-feature-implementation`
- `unity-bug-investigation`
- `unity-project-health-check`
- manual project changes
- package changes
- scene or prefab changes
- release preparation

Use project context from:

- `unity-project-onboarding`
- `Docs/AI/UnityProjectContext.md`
- repository instructions
- build documentation
- CI workflows

Do not repeat broad architecture analysis unless it is required to understand a
validation failure.

## Default behavior

Validation may execute tests, enter Play Mode, or trigger builds when those
operations are appropriate and available.

Do not modify production code or project assets merely to make validation pass.

Do not:

- disable failing tests
- clear the Console before recording the baseline
- suppress warnings without understanding them
- change build settings casually
- update packages
- delete user data
- rewrite scenes or prefabs
- mark a build ready based only on static inspection

## Knowledge routing

The skill contains:

- `foundations/`: validation principles
- `checklists/`: validation domains
- `frameworks/`: framework and platform-specific rules
- `references/`: plans, reports, status definitions, and capabilities

### Mandatory foundations

Always read:

- `foundations/evidence-levels.md`
- `foundations/baseline-and-regression.md`
- `foundations/validation-safety.md`
- `foundations/status-and-reporting.md`

### Checklist routing

| Validation domain | File |
|---|---|
| Compilation and Console | `checklists/compilation-and-console.md` |
| EditMode and PlayMode tests | `checklists/tests.md` |
| Scenes and Build Settings | `checklists/scenes-and-build-settings.md` |
| Prefabs and serialization | `checklists/prefabs-and-serialization.md` |
| Runtime smoke testing | `checklists/runtime-smoke-tests.md` |
| Builds and artifacts | `checklists/builds-and-artifacts.md` |
| Packages and assemblies | `checklists/packages-and-assemblies.md` |
| Performance budgets | `checklists/performance-budgets.md` |
| Multiplayer validation | `checklists/multiplayer.md` |
| Save and migration validation | `checklists/save-and-migration.md` |
| UI, localization, and input | `checklists/ui-localization-input.md` |
| Rendering, shaders, and VFX | `checklists/rendering-shaders-vfx.md` |
| XR and devices | `checklists/xr-and-devices.md` |
| CI and reproducibility | `checklists/ci-and-reproducibility.md` |
| Release candidate validation | `checklists/release-candidate.md` |

### Framework routing

Read framework guidance only when active use is confirmed.

| Framework or platform | File |
|---|---|
| Photon Fusion | `frameworks/networking/fusion.md` |
| Netcode for GameObjects | `frameworks/networking/netcode-for-gameobjects.md` |
| Mirror | `frameworks/networking/mirror.md` |
| FishNet | `frameworks/networking/fishnet.md` |
| URP | `frameworks/rendering/urp.md` |
| HDRP | `frameworks/rendering/hdrp.md` |
| Windows | `frameworks/platforms/windows.md` |
| Android | `frameworks/platforms/android.md` |
| iOS | `frameworks/platforms/ios.md` |
| WebGL | `frameworks/platforms/webgl.md` |
| Linux | `frameworks/platforms/linux.md` |
| macOS | `frameworks/platforms/macos.md` |
| Dedicated server | `frameworks/platforms/dedicated-server.md` |

## Validation modes

### Change validation

Use after a specific implementation or bug fix.

Focus on:

- changed assemblies
- affected scenes and prefabs
- relevant tests
- original behavior or reproduction
- regression surface

### Project validation

Use for a general readiness check.

Focus on:

- project compilation
- Console baseline
- test suites
- build scenes
- target build
- critical assets

### Release candidate validation

Use before publishing or handing off a build.

Include:

- clean build
- target platform
- release configuration
- smoke tests
- save compatibility
- networking
- performance budgets
- version and artifact metadata
- reproducibility

### CI validation

Use when validating automated commands or pipelines.

Confirm:

- command reproducibility
- exit codes
- test result artifacts
- build artifacts
- environment requirements
- secret handling
- failure visibility

## Core principles

1. Record the baseline before running validation.
2. Distinguish pre-existing failures from regressions.
3. Validate the changed surface first.
4. Progress from cheap to strong evidence.
5. Use the actual target platform when required.
6. Report exact commands, tests, scenes, and artifacts.
7. Do not claim runtime behavior from compilation.
8. Do not claim multiplayer correctness from one instance.
9. Do not claim visual correctness without visual inspection.
10. Do not claim performance compliance without measurement.
11. Preserve failing evidence.
12. Report blocked and unverified areas explicitly.

## Phase 1: Define validation contract

Determine:

- what change or project state is being validated
- acceptance criteria
- target platform
- build configuration
- scenes or features involved
- required test suites
- required runtime scenarios
- performance or memory budgets
- multiplayer topology
- device or XR requirements
- artifact expectations
- release stage

If no explicit criteria exist, infer the smallest meaningful validation set from
the change and project context.

## Phase 2: Establish baseline

Before changing state:

- record Git commit and working tree status
- inspect changed files
- read current Console messages
- record known failing tests
- record Unity and package versions
- record active target platform
- record Build Settings scenes
- identify existing build and CI commands
- identify required environment variables without exposing their values

Do not clear the Console until baseline evidence is preserved.

## Phase 3: Select validation level

Use `foundations/evidence-levels.md`.

Choose the strongest practical level required by the change.

Examples:

- plain C# calculation: compile + EditMode tests
- MonoBehaviour lifecycle: compile + PlayMode or runtime
- prefab integration: compile + serialized reference inspection + runtime
- multiplayer: multi-peer validation
- shader: shader compilation + visual validation
- platform API: target build + target device
- save migration: old save + new save + reload
- performance fix: before/after measurement

## Phase 4: Validate compilation and Console

Use `checklists/compilation-and-console.md`.

When Unity is connected:

1. Confirm active project.
2. Allow import and compilation to finish.
3. Read Console errors and warnings.
4. Separate pre-existing messages from new messages.
5. Identify assembly or package failures.
6. Do not clear messages needed as evidence.

When Unity is unavailable, use the strongest fallback:

- CI compilation
- generated solution compilation
- static analysis
- assembly-specific commands

Report that Unity Editor compilation was not confirmed.

## Phase 5: Run tests

Use `checklists/tests.md`.

Prefer targeted tests first, then broader suites.

Record:

- test category
- test names or filters
- passed
- failed
- skipped
- duration when useful
- pre-existing versus new failures
- test result artifact paths

Do not disable or ignore failures to obtain a green result.

## Phase 6: Validate scenes and serialized assets

Use:

- `checklists/scenes-and-build-settings.md`
- `checklists/prefabs-and-serialization.md`

Confirm:

- required scenes exist
- enabled scenes are correct
- startup flow is valid
- no required references are missing
- prefab variants remain valid
- ScriptableObject defaults are safe
- new `.meta` files exist
- no unintended broad serialization changes occurred

Do not open and save scenes merely to inspect them.

## Phase 7: Runtime smoke test

Use `checklists/runtime-smoke-tests.md`.

Exercise the smallest runtime scenario that proves the changed behavior.

Record:

- scene
- object or feature
- steps
- expected result
- observed result
- Console state
- repetitions
- cleanup or reload behavior

Do not say “tested in Play Mode” without stating what was exercised.

## Phase 8: Build target artifacts

Use `checklists/builds-and-artifacts.md`.

When a target build is required:

- confirm platform
- confirm configuration
- confirm scenes
- confirm output path
- record command or build method
- record duration when useful
- inspect warnings and failures
- verify artifact existence
- verify artifact metadata
- launch or install when appropriate

A successful Editor compile does not prove a player build succeeds.

## Phase 9: Run framework and platform checks

Load the relevant framework and platform guides.

Examples:

- networking topology
- dedicated-server symbols
- WebGL threading restrictions
- Android permissions and ABI
- iOS signing and IL2CPP
- Windows architecture
- shader and graphics API support

Do not mark platform validation complete without platform-relevant evidence.

## Phase 10: Validate acceptance criteria

Use a traceable matrix:

- criterion
- evidence
- status
- limitation

Every acceptance criterion must be:

- Passed
- Failed
- Blocked
- Not run
- Not applicable

Do not omit failed criteria from the final report.

## Phase 11: Review working tree and artifacts

Before completion:

- inspect final diff
- identify generated files
- identify unintended changes
- ensure temporary diagnostics are removed
- ensure test artifacts are stored appropriately
- ensure build artifacts are outside source directories unless expected
- ensure secrets were not written to logs or reports
- record artifact paths

## Phase 12: Assign validation status

Use `foundations/status-and-reporting.md`.

Allowed overall statuses:

- Ready
- Ready with limitations
- Blocked
- Failed
- Not validated

Do not use Ready when a required criterion was not run.

## Prohibited behavior

Do not:

- declare success from compilation alone
- hide failing tests
- clear evidence before recording it
- change code to silence tests without understanding the failure
- remove scenes from Build Settings to make a build pass
- disable stripping, signing, or platform constraints casually
- update dependencies during validation
- replace test data
- skip the original bug reproduction
- claim two-peer validation from one process
- claim performance improvement without equivalent measurements
- claim visual quality from code inspection
- expose signing credentials or tokens

## Definition of done

Validation is complete when:

- scope and acceptance criteria are explicit
- baseline is recorded
- required validation levels are selected
- compilation status is known
- Console regressions are classified
- required tests were run
- scenes and serialized assets were checked
- runtime behavior was exercised when required
- target build was produced when required
- framework and platform checks were applied
- acceptance criteria have statuses
- final diff and artifacts were reviewed
- overall status is assigned honestly
- limitations are explicit

## Final response

Return:

### Status

Ready / Ready with limitations / Blocked / Failed / Not validated

### Validation summary

Summarize the strongest evidence.

### Acceptance criteria

List each criterion and status.

### Tests and builds

Include exact suites, platforms, and artifact paths.

### Regressions

State new, pre-existing, and unresolved failures.

### Limitations

State what was not validated and why.

### Recommended next action

Include only the most important action required to reach Ready.

Referenced files: 39

View saved version →

---
name: unity-feature-implementation
description: Implement, extend, or integrate a feature in an existing Unity project while respecting its architecture, coding conventions, scene structure, packages, networking model, and validation workflow. Use when the user asks to add gameplay mechanics, UI behavior, systems, editor tools, integrations, ScriptableObjects, shaders, VFX, networking functionality, save systems, input behavior, XR interactions, audio, animation, AI, or other concrete Unity features.
---

# Unity Feature Implementation

Implement Unity features as coherent additions to the existing project.

Do not treat a feature request as an isolated code-generation task. Understand
how the project currently solves related problems, identify the correct
extension points, implement the smallest complete solution, and validate it
using the strongest available evidence.

## Surface Limits

If the current surface is Chat mode without an attached workspace, repository files, or local filesystem access, do not claim that you can implement or validate changes in the user's Unity project. Explain that Unity Essentials can help reason from pasted code or screenshots, but real implementation requires Codex with the Unity project folder open.

If Codex has a workspace or local files available, inspect the project before editing and report validation honestly.

## Primary outcome

Deliver a working implementation that:

- follows the project's existing architecture
- respects current coding conventions
- integrates with existing systems
- avoids unnecessary dependencies
- minimizes scene and prefab changes
- compiles without new errors
- includes appropriate tests or validation
- documents assumptions and remaining setup

## Relationship with project onboarding

Before implementing a substantial feature, look for an existing project context
document such as:

- `Docs/AI/UnityProjectContext.md`
- `Docs/UnityProjectContext.md`
- project-specific AI or architecture documentation

If no reliable context exists and the project is unfamiliar, use the
`unity-project-onboarding` workflow first.

Do not repeat a complete onboarding when the necessary project context is
already current and supported by repository evidence.

## Knowledge routing

Before planning or editing, determine which internal guidance applies.

The skill contains three categories:

- `foundations/`: cross-cutting engineering rules
- `specializations/`: rules for a particular feature area
- `frameworks/`: rules for a concrete Unity package or technology

Read only the files that materially apply.

### Mandatory foundations

For every non-trivial runtime feature, read:

- `foundations/architecture-and-clean-code.md`
- `foundations/unity-lifecycle.md`
- `foundations/testing.md`

Read `foundations/serialization-safety.md` when the change affects:

- serialized fields
- scenes
- prefabs
- ScriptableObjects
- materials
- animation controllers
- project settings
- input action assets

Read `foundations/performance-basics.md` when the feature affects:

- frequently executed runtime code
- Update, FixedUpdate, or LateUpdate
- spawning
- collections
- networking
- rendering
- UI refreshes
- asset loading

### Specialization routing

A task may use more than one specialization.

| Area | File |
|---|---|
| Gameplay mechanics | `specializations/gameplay.md` |
| Player input | `specializations/input.md` |
| UI and HUD | `specializations/ui.md` |
| Multiplayer | `specializations/multiplayer.md` |
| Save data | `specializations/save-systems.md` |
| Shaders and rendering behavior | `specializations/shaders.md` |
| Particle System and VFX Graph | `specializations/vfx.md` |
| Editor extensions | `specializations/editor-tools.md` |
| XR and VR | `specializations/xr.md` |
| Audio | `specializations/audio.md` |
| Animation systems | `specializations/animation.md` |
| Navigation and gameplay AI | `specializations/ai-navigation.md` |
| Explicit optimization work | `specializations/performance.md` |

### Framework routing

Read a framework guide only when the project actively uses that framework.

Do not select a framework merely because its package is installed.

Confirm usage through:

- project context
- package configuration
- assembly references
- first-party code
- scenes or prefabs
- project documentation

### Resolution priority

When guidance conflicts, use this priority:

1. Explicit user requirements
2. Repository instructions and project architecture
3. Data integrity and safety requirements
4. Framework-specific guidance
5. Feature specialization guidance
6. Foundation guidance
7. Generic Unity conventions

Existing project architecture should normally be extended rather than replaced.

## Proportional architecture

The architectural complexity of the solution must be proportional to:

- feature complexity
- number of consumers
- expected variation
- lifetime of the system
- project size
- testing requirements
- networking or persistence requirements

Do not introduce an abstraction solely because a design principle can be
applied.

Prefer the simplest design that preserves clear ownership, cohesion,
testability, and safe future change.

## Feature workflow

1. Interpret the request as a concrete feature contract.
2. Read project context and relevant repository instructions.
3. Route to the required foundations, specializations, and frameworks.
4. Locate the correct integration points.
5. Assess risk.
6. Create a focused implementation plan.
7. Implement incrementally.
8. Compile and inspect Console output.
9. Run relevant tests.
10. Validate runtime behavior where possible.
11. Review the final diff.
12. Report completed work, validation, setup, and limitations.

## Feature contract

Identify:

- desired player or developer behavior
- feature entry point
- expected output or effect
- affected systems
- supported platforms
- multiplayer implications
- persistence implications
- UI implications
- performance expectations
- failure and edge cases
- explicit constraints
- acceptance criteria

Do not silently broaden the scope.

When requirements are incomplete, infer the smallest conventional behavior that
fits the existing project.

Ask a question only when an unresolved choice would substantially change the
public API, architecture, data format, network behavior, or visible result.
Otherwise, make a conservative decision and document it.

## Integration analysis

Before editing, answer:

1. Which existing component owns this responsibility?
2. Which assembly should contain the new code?
3. Is there already an extension point?
4. Does the project favor composition, inheritance, events, or services here?
5. Is configuration stored in prefabs, ScriptableObjects, settings, or code?
6. Does this behavior require scene or prefab wiring?
7. Who owns state authority in multiplayer?
8. What behavior must remain unchanged?
9. What is the smallest coherent file set?
10. How will the feature be verified?

Do not create a new manager, singleton, service locator, event bus, or framework
when an existing system already covers the responsibility.

## Risk classification

### Low risk

- isolated plain C# logic
- utility methods
- non-breaking configuration additions
- EditMode tests
- localized editor-only tooling

### Medium risk

- modifying runtime MonoBehaviours
- adding input handling
- changing ScriptableObject schemas
- adding runtime UI
- extending state machines
- modifying a prefab with limited usage

### High risk

- editing shared scenes or base prefabs
- changing public APIs used across assemblies
- modifying network authority
- changing serialization layouts
- changing addressable keys
- altering render-pipeline settings
- changing initialization order
- modifying Build Settings
- changing persistent save formats

For medium- and high-risk changes, identify affected assets, rollback strategy,
compatibility concerns, and required validation.

## Implementation rules

- Extend existing systems before creating parallel systems.
- Prefer the smallest coherent implementation.
- Avoid unrelated refactors.
- Preserve public APIs unless change is necessary.
- Search all usages before changing public members.
- Preserve serialized field names where possible.
- Use `FormerlySerializedAs` when renaming serialized fields.
- Follow existing async, DI, event, and state-management patterns.
- Keep Unity lifecycle methods understandable.
- Keep mutable state ownership clear.
- Avoid hidden dependencies.
- Do not add packages without explicit need and authorization.
- Do not edit generated directories or IDE artifacts.
- Do not claim validation that did not occur.

## Unity tooling

Use conceptual capabilities rather than hardcoded MCP tool names.

Read capabilities may include:

- `unity.connection.status`
- `unity.console.read`
- `unity.scene.inspect`
- `unity.buildsettings.read`
- `unity.gameobject.inspect`
- `unity.asset.search`
- `unity.tests.list`
- `unity.playmode.read`

Mutation capabilities may include:

- `unity.script.create`
- `unity.script.modify`
- `unity.asset.modify`
- `unity.gameobject.modify`
- `unity.scene.modify`
- `unity.playmode.set`
- `unity.tests.run`

Before invoking a mutating tool:

1. Confirm it targets the active Unity project.
2. Understand its side effects.
3. Prefer the most narrowly scoped operation.
4. Preserve existing serialized data.
5. Re-read affected state after mutation.
6. Check Console output after imports or recompilation.

## Definition of done

A feature is complete when:

- requested behavior is clearly understood
- correct integration points were identified
- implementation follows project architecture and conventions
- necessary code and safe asset changes are complete
- Unity or the strongest available fallback compiles
- no new unresolved errors were introduced
- relevant tests pass or limitations are reported
- runtime behavior was validated at an appropriate level
- serialized references and setup requirements are accounted for
- final diff contains no unrelated changes
- assumptions and risks are documented
- remaining manual steps are explicit
- documentation is updated when necessary

## Final response

Return:

### Implemented

Summarize completed behavior.

### Changed files

List important created and modified files with purpose.

### Validation

State exactly what was validated.

### Setup

List required Inspector, scene, prefab, input, package, or build setup.

### Assumptions and limitations

Record important assumptions and remaining risks.

Referenced files: 37

View saved version →

---
name: unity-mcp-workflow
description: Use when working on Unity projects with Codex, especially when selecting or connecting a Unity MCP provider, validating Unity Editor connectivity, debugging scenes/prefabs/scripts, or deciding what Unity workflows should be automated.
---

# Unity MCP Workflow

Use this skill when the user asks Codex to work with Unity or to connect Codex to Unity through MCP.

## Surface And Workspace Limits

First determine whether the current surface can actually inspect the user's Unity project.

In Chat mode without an attached workspace, repository files, or local filesystem access, do not claim that you can connect to or inspect the user's Unity project. Explain that Unity Essentials can guide the user conceptually from information they provide, but it cannot verify `Assets/`, `Packages/manifest.json`, Unity Editor state, or MCP configuration from plain chat alone. Recommend using Codex with the Unity project folder open when the user wants the plugin to inspect files, detect MCP setup, or validate the Unity connection.

In Codex with a workspace or local files available, inspect the real project before giving connection instructions.

Do not tell the user to install this Codex plugin, its internal package name, or any previous package name as if it were a Unity-side MCP requirement. Unity Essentials is a workflow plugin for Codex, not a Unity Editor MCP bridge. The Unity-side bridge should be one of the actual Unity MCP providers detected or selected below.

When there is no workspace, use language like:

```text
I cannot inspect or connect to your Unity project from this chat alone because I do not have access to the project folder or Unity Editor state here. I can explain the setup conceptually from what you paste, but for automatic project detection and MCP validation, open the Unity project in Codex and ask me there.
```

## MCP Discovery First

Before recommending or installing any Unity MCP provider, check whether the project already has one.

Look for evidence in:

- `Packages/manifest.json`
- `Packages/packages-lock.json`
- embedded packages under `Packages/`
- project folders or package names containing `mcp`, `unity-mcp`, `com.unity.ai.assistant`, `coplay`, `ai-game`, `ivanmurzak`, or `codergamester`
- existing MCP client config files such as `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, or other repo-documented MCP setup
- active MCP tools already available to Codex in the current thread

If a Unity MCP is already installed, do not recommend adding another one by default. Prefer using and validating the existing bridge first. Multiple Unity MCP bridges can duplicate tools, confuse tool selection, increase token usage, and make debugging harder.

If no MCP evidence is found, state that no Unity MCP was detected and ask whether the user wants to add one. If they do, guide them through choosing exactly one provider that fits their situation. If they do not, continue with repository-only workflows and clearly report that Unity Editor actions, console reads, scene inspection through the Editor, and live validation are unavailable.

## Provider Selection

Prefer this order unless the user explicitly asks for a specific provider:

1. Official Unity MCP: choose this when the project uses Unity 6 or newer, has the AI Assistant package available, and the user has the needed Unity AI trial or subscription. It is the most conservative default because it is documented by Unity and requires explicit approval for direct external clients.
2. CoplayDev/unity-mcp: choose this when the user wants a popular open-source bridge, needs broad editor automation, or cannot use the official Unity AI package. Inspect the current repository documentation before giving install commands because the project evolves quickly.
3. IvanMurzak/Unity-MCP: consider this when the user wants a full AI development loop, generated skills, runtime/in-game MCP behavior, or a CLI-first setup.
4. CoderGamester/mcp-unity: consider this when the user wants a Node.js-backed open-source Unity Editor bridge with Codex/Cursor/Claude-style client support.

Do not silently install a community MCP server into a Unity project. Explain the tradeoff and ask for confirmation before installing packages or running installer commands that modify the project.

Use these questions to choose a provider:

- If the user wants the official/supportable path and has Unity 6 plus Unity AI access, choose Official Unity MCP.
- If the user wants the most popular open-source bridge with broad editor automation, choose CoplayDev/unity-mcp.
- If the user wants generated agent skills, CLI setup, many built-in tools, or runtime/in-game AI workflows, choose IvanMurzak/Unity-MCP.
- If the user wants a lighter Node.js-backed open-source Editor bridge, choose CoderGamester/mcp-unity.
- If the project already has one provider installed, use that provider unless there is a clear reason to replace it.

## Connection Workflow

Before using Unity MCP tools or claiming Unity is connected:

1. Identify the current Unity project root. Check for `Assets/`, `Packages/manifest.json`, and `ProjectSettings/ProjectVersion.txt`.
2. Check the Unity version from `ProjectSettings/ProjectVersion.txt`.
3. Determine whether any MCP provider is already installed or configured.
4. Verify the editor is open and the MCP bridge/server is running.
5. If direct approval is required in Unity, tell the user exactly where to approve the client.
6. Run a low-risk probe first, such as reading the scene hierarchy or console messages.

If no Unity MCP provider is installed or configured, the correct connection guidance is:

1. Explain that no Unity MCP was detected in the project.
2. Ask whether the user wants to add an MCP bridge.
3. If yes, choose one provider using the provider-selection rules below and follow that provider's current official/repository setup instructions.
4. If no, continue without MCP using normal repository tools and report the limitations.

Never replace this flow with a request to install Unity Essentials or any Codex-side plugin again.

When a workspace exists but no MCP is detected, use language like:

```text
I found the Unity project, but I do not see a Unity MCP bridge configured in this project yet. I can keep working from repository files only, or I can help you choose and add one Unity MCP provider. Do you want to add an MCP bridge?
```

For official Unity MCP, remember:

- The Unity MCP bridge is configured in `Edit > Project Settings > AI > Unity MCP`.
- The local relay is installed under `~/.unity/relay/`.
- Manual client configuration points to the relay executable with `--mcp`.
- Direct external clients require approval in Unity.

For community providers, inspect the installed package and repository docs in the current turn before relying on remembered setup details.

## Installation Policy

- Install at most one Unity MCP provider per project unless the user explicitly asks for a multi-provider experiment.
- Do not install all known MCPs.
- Do not add, update, or remove Unity packages without explicit user confirmation.
- If an MCP exists but appears broken, troubleshoot it before suggesting replacement.
- If replacement is justified, explain the migration plan and ask before making changes.
- Prefer a small connection proof before deeper automation: read Unity version, read console, or inspect scene hierarchy.

## Unity Work Rules

- Read local project files and Unity state before proposing changes.
- Preserve user scene, prefab, and asset changes. Do not revert Unity-generated files unless the user explicitly asks.
- Prefer Editor-safe changes over hand-editing YAML assets. Hand-edit `.prefab`, `.unity`, or `.asset` YAML only when the format and object IDs are understood.
- For script edits, respect existing assembly definitions, namespaces, serialization, and Unity lifecycle conventions.
- After script changes, check compile errors through Unity console or available project build/test commands.
- For prefab/scene changes, verify the actual object path and component wiring after edits.
- For play-mode or destructive actions, explain the action and get user confirmation if it can modify runtime state, assets, or open scenes.

## Useful Unity Capabilities To Offer

When the user asks what else would be useful for Unity, suggest capabilities like these:

- Connection doctor: verify Unity version, MCP provider, relay/server process, package install, and client approval state.
- Console triage loop: read console errors, map them to scripts/assets, patch the cause, and re-check.
- Scene/prefab inspector: summarize hierarchy, missing scripts, broken references, inactive objects, and suspicious component values.
- Serialized reference tracer: follow prefab/fileID/GUID links from YAML into scripts, materials, sprites, addressables, and localized assets.
- Test runner helper: run EditMode/PlayMode tests and summarize failures.
- Build readiness checks: inspect build target, scenes in build, scripting backend, addressables, define symbols, and common platform issues.
- Asset hygiene checks: find missing meta files, duplicate GUIDs, large assets, unused assets, texture import issues, and audio compression problems.
- Custom MCP tool authoring: create project-specific Editor tools for repetitive tasks such as localization validation, prefab audits, or scene setup.
- XR/mobile checks: inspect input actions, quality settings, safe-area layout, touch gestures, and platform-specific player settings.

## Helper Scripts

This plugin includes `scripts/unity_mcp_advisor.py`. Use it for a quick local recommendation from a Unity project path and an optional provider:

```powershell
python "%PLUGIN_ROOT%\scripts\unity_mcp_advisor.py" --project "C:\path\to\UnityProject" --provider official
```

Provider values: `auto`, `official`, `coplaydev`, `ivanmurzak`, `codergamester`.

The script reports existing MCP evidence before recommending a provider.

View saved version →

---
name: unity-project-health-check
description: Audit the technical health of an existing Unity project without making changes by default. Use when the user asks for a project review, technical audit, architecture review, performance scan, package review, build readiness check, maintainability assessment, risk analysis, or general Unity project health report. Inspect evidence across code, assemblies, scenes, prefabs, packages, settings, tests, performance-sensitive paths, networking, rendering, persistence, and build configuration. Produce prioritized findings with severity, confidence, evidence, impact, and recommended next actions.
---

# Unity Project Health Check

Assess the technical health of a Unity project using evidence from the
repository and, when available, the connected Unity Editor.

The default mode is read-only.

Do not automatically fix findings unless the user explicitly asks for
remediation.

## Surface Limits

If the current surface is Chat mode without an attached workspace, repository files, or local filesystem access, do not present a project health report as if the project was audited. Explain that Unity Essentials can provide an audit checklist or review pasted evidence, but a real health check requires Codex with the Unity project folder open.

If Codex has a workspace or local files available, keep the audit evidence-based and read-only by default.

## Primary outcome

Produce a concise, prioritized report that answers:

- What is healthy?
- What is risky?
- What is broken or likely to break?
- What should be fixed first?
- Which findings are confirmed, likely, or unknown?
- Which checks could not be completed?

## Relationship with onboarding

Look for an existing context document:

- `Docs/AI/UnityProjectContext.md`
- `Docs/UnityProjectContext.md`
- architecture documentation
- repository instructions

If no reliable project context exists, use the
`unity-project-onboarding` workflow first or perform the minimum equivalent
inspection needed for the audit.

Do not duplicate complete onboarding findings in the health report.

## Default behavior

The health check is read-only unless explicitly requested otherwise.

Do not:

- modify code
- edit scenes or prefabs
- install or update packages
- change Project Settings
- enter Play Mode without a validation need
- trigger builds without a clear reason
- clear the Console
- rewrite documentation
- delete generated folders

## Knowledge routing

The skill contains:

- `foundations/`: audit principles and reporting rules
- `checklists/`: health domains
- `frameworks/`: framework-specific review criteria
- `references/`: templates, scoring, and capability guidance

Read only the areas relevant to the requested scope.

### Mandatory foundations

Always read:

- `foundations/evidence-and-confidence.md`
- `foundations/severity-and-prioritization.md`
- `foundations/read-only-audit-safety.md`
- `foundations/reporting-quality.md`

### Checklist routing

| Audit area | File |
|---|---|
| Architecture and coupling | `checklists/architecture-and-maintainability.md` |
| Code quality and C# risks | `checklists/code-quality.md` |
| Unity lifecycle and initialization | `checklists/lifecycle-and-initialization.md` |
| Assemblies and dependencies | `checklists/assemblies-and-dependencies.md` |
| Packages and compatibility | `checklists/packages-and-compatibility.md` |
| Scenes, prefabs, and serialization | `checklists/scenes-prefabs-serialization.md` |
| Performance and allocations | `checklists/performance.md` |
| Memory and asset loading | `checklists/memory-and-assets.md` |
| Rendering, shaders, and VFX | `checklists/rendering-and-vfx.md` |
| Multiplayer and networking | `checklists/multiplayer.md` |
| Save data and persistence | `checklists/save-and-persistence.md` |
| UI, localization, and accessibility | `checklists/ui-localization-accessibility.md` |
| Input and device support | `checklists/input-and-device-support.md` |
| Tests and validation | `checklists/testing-and-validation.md` |
| Builds, platforms, and CI | `checklists/builds-platforms-ci.md` |
| Security and secrets | `checklists/security-and-secrets.md` |
| Editor tooling and imports | `checklists/editor-tooling-and-imports.md` |
| Project hygiene and version control | `checklists/project-hygiene.md` |

### Framework routing

Read framework guidance only when active use is confirmed.

| Framework | File |
|---|---|
| Photon Fusion | `frameworks/networking/fusion.md` |
| Netcode for GameObjects | `frameworks/networking/netcode-for-gameobjects.md` |
| Mirror | `frameworks/networking/mirror.md` |
| FishNet | `frameworks/networking/fishnet.md` |
| URP | `frameworks/rendering/urp.md` |
| HDRP | `frameworks/rendering/hdrp.md` |

## Audit modes

### Focused

Use when the user asks about one area, such as performance or architecture.

Inspect only the relevant domains and immediate dependencies.

### Standard

Use for a general project health review.

Inspect all high-value domains, but sample large repositories rather than
reading every file.

### Release readiness

Use before a milestone, demo, submission, or launch.

Prioritize:

- compilation
- Console
- tests
- scenes
- builds
- packages
- missing references
- platform issues
- persistence
- severe performance risks

### Deep audit

Use only when explicitly requested or clearly justified.

May include:

- broad code sampling
- full assembly analysis
- package compatibility review
- profiler capture
- build validation
- multi-peer networking review
- target-device validation

## Core principles

1. Evidence before conclusions.
2. Read-only by default.
3. Separate confirmed defects from code smells.
4. Prioritize impact, not stylistic preference.
5. Respect existing architecture.
6. Do not recommend rewrites without strong justification.
7. Prefer actionable findings.
8. Avoid generic Unity advice.
9. Do not count generated or vendor code as first-party debt.
10. Report audit limitations.
11. Do not claim runtime, build, or platform validation that did not occur.
12. Keep the report proportionate to the project and request.

## Phase 1: Define audit scope

Determine:

- focused, standard, release readiness, or deep audit
- target platform
- Unity version
- project size
- active frameworks
- performance requirements
- multiplayer requirements
- release stage
- known concerns
- whether Editor tools are available

If the user did not specify scope, use a standard read-only audit.

## Phase 2: Establish baseline

Inspect:

- project context
- Unity version
- package manifest and lock file
- repository instructions
- current Console messages
- current test status
- build scene configuration
- first-party assemblies
- top-level first-party directories
- recent relevant changes when useful

Distinguish pre-existing known issues from newly discovered findings.

## Phase 3: Separate first-party and vendor code

Identify likely:

- first-party code
- embedded packages
- third-party packages
- generated source
- imported Asset Store content
- examples and samples
- test fixtures
- build artifacts

Do not report vendor implementation details as project-owned issues unless the
project integration creates the risk.

## Phase 4: Route to audit domains

Select the required checklists.

For a standard audit, normally include:

- architecture
- code quality
- lifecycle
- assemblies
- packages
- scenes and serialization
- performance
- memory and assets
- tests
- builds
- project hygiene

Include networking, rendering, UI, input, persistence, or editor tooling when
the project actively uses them.

## Phase 5: Gather evidence

Use:

- configuration files
- package metadata
- assembly definitions
- representative first-party code
- scene and prefab inspection
- Console messages
- test results
- profiler data
- build logs
- Git metadata
- project documentation

Sample intelligently.

Do not read every file unless the audit requires it.

## Phase 6: Record findings

Use `references/finding-template.md`.

Each finding should contain:

- title
- domain
- severity
- confidence
- evidence
- impact
- recommendation
- remediation size
- validation needed
- affected paths

Do not report a style preference as a defect.

## Phase 7: Deduplicate and group

Combine findings that share one root cause.

Example:

Do not report ten separate missing-reference symptoms when they all result from
one broken prefab base.

Group findings by:

- architecture
- correctness
- performance
- maintainability
- release risk
- data integrity
- platform compatibility

## Phase 8: Prioritize

Use `references/health-scoring.md`.

Prioritize based on:

- user impact
- crash or data-loss risk
- release-blocking potential
- frequency
- scope
- recovery difficulty
- confidence
- remediation cost

Do not prioritize a low-impact clean-code issue above a build failure or save
corruption risk.

## Phase 9: Identify healthy areas

Report meaningful positive findings.

Examples:

- clear assembly boundaries
- reliable automated tests
- no new Console errors
- consistent serialization practices
- strong package pinning
- clean networking authority model
- controlled asset loading

Do not add empty praise.

## Phase 10: Recommend next actions

Provide an ordered action plan.

Each action should state:

- expected benefit
- affected finding IDs
- likely effort
- required validation
- whether it can be handled by another plugin skill

Recommended routing:

- feature changes → `unity-feature-implementation`
- root-cause investigation → `unity-bug-investigation`
- final verification → `unity-build-validation`

## Phase 11: Optional baseline artifact

When useful, create or update:

`Docs/AI/UnityProjectHealth.md`

Use `references/health-report-template.md`.

Do not create a persistent report when the user requested only a quick review.

When updating an existing report:

- preserve manually authored notes
- update stale findings
- close resolved findings
- keep stable finding IDs
- record analyzed commit and date

## Severity definitions

### Critical

Likely to cause:

- data loss
- security exposure
- consistent crash
- broken production build
- severe multiplayer integrity failure
- project corruption

### High

Likely to cause:

- major feature failure
- frequent runtime errors
- serious release risk
- major platform incompatibility
- severe performance degradation
- save migration failure

### Medium

Meaningful maintainability, correctness, performance, or workflow risk.

### Low

Limited impact, localized debt, or preventive improvement.

### Informational

Useful observation with no immediate corrective need.

## Confidence definitions

### Confirmed

Directly demonstrated through configuration, code, Editor state, tests,
profiling, build output, or reproducible behavior.

### Likely

Supported by several consistent signals but not directly reproduced.

### Possible

Plausible and worth checking, but evidence is incomplete.

Do not assign high severity with weak confidence without clearly explaining the
uncertainty.

## Definition of done

The health check is complete when:

- scope is explicit
- baseline is recorded
- first-party and vendor code are separated
- relevant domains were inspected
- findings contain evidence
- severity and confidence are assigned
- duplicates are grouped
- healthy areas are identified
- limitations are explicit
- next actions are prioritized
- no unintended project changes were made
- persistent report is created only when appropriate

## Final response

Return:

### Overall health

A concise assessment and major theme.

### Highest-priority findings

List only the most important findings with severity and confidence.

### Healthy areas

Mention meaningful strengths.

### Recommended order

Provide the most useful remediation sequence.

### Audit coverage

State what was and was not checked.

### Report path

Include the persistent report path when created.

Referenced files: 35

View saved version →

---
name: unity-project-onboarding
description: Analyze and document an unfamiliar Unity project before substantial work begins. Use when opening, cloning, inheriting, reviewing, or starting work in a Unity repository; when the user asks to understand the project architecture; or before implementing a feature without sufficient project context. Detect Unity version, packages, render pipeline, input, networking, tests, assemblies, scenes, conventions, and available Unity MCP capabilities. Produce a persistent project context document without modifying Unity assets.
---

# Unity Project Onboarding

Understand the Unity project before making substantial changes.

This skill performs a read-only inspection of the repository and, when available, the connected Unity Editor. It produces a concise persistent description that future agents can use when working on the project.

## Surface Limits

If the current surface is Chat mode without an attached workspace, repository files, or local filesystem access, do not claim that you inspected the Unity project. Explain that Unity Essentials can give conceptual guidance from pasted files or screenshots, but a real onboarding requires Codex with the Unity project folder open.

If Codex has a workspace or local files available, verify the project root from actual files before producing findings.

## Primary outcome

Create or update:

`Docs/AI/UnityProjectContext.md`

If the project already uses another documentation location, prefer that location instead of creating a competing structure.

Do not create the document when the user only requested a quick explanation. In that case, return the findings directly.

## Core Principles

1. Inspect before modifying.
2. Prefer repository evidence over assumptions.
3. Separate confirmed facts from inferred conclusions.
4. Do not require a Unity MCP.
5. Use an available MCP only when it provides useful additional evidence.
6. Do not open or modify scenes merely to collect information.
7. Keep the generated context concise and useful for future tasks.
8. Preserve useful manually written documentation.
9. Never report a framework as installed solely because its name appears in generated or cached files.
10. Treat `Library/`, `Temp/`, `Logs/`, `obj/`, and build output as generated directories unless the project explicitly documents otherwise.

## MCP Policy

During onboarding, detect whether the project already has a Unity MCP provider before suggesting a new one.

Check:

- `Packages/manifest.json`
- `Packages/packages-lock.json`
- embedded packages under `Packages/`
- project MCP client config files
- currently available Codex MCP tools

Record existing MCP/tooling as `available`, `unavailable`, or `unverified`.

Do not install, update, remove, or replace MCP packages during onboarding. If no MCP exists, state that Unity work can continue from repository evidence and ask whether the user wants help choosing one.

## Phase 1: Verify The Project

Confirm that the current repository is a Unity project by looking for:

- `Assets/`
- `Packages/manifest.json`
- `ProjectSettings/ProjectVersion.txt`

If one or more are missing, search parent and immediate child directories for a Unity project root. If exactly one valid project root exists, use it. If multiple Unity projects exist, report them and inspect the project most relevant to the user's request. Do not create a Unity context document for an unverified project.

Record the resolved Unity project root.

## Phase 2: Read Existing Guidance

Before analyzing implementation details, locate existing project instructions.

Check for:

- `AGENTS.md`
- `CLAUDE.md`
- `README.md`
- `CONTRIBUTING.md`
- files under `Docs/`
- files under `.github/`
- existing AI context or architecture documentation

Extract naming conventions, folder conventions, architectural rules, testing requirements, supported platforms, prohibited changes, package-management rules, and build instructions.

Project-specific instructions override generic recommendations in this skill.

## Phase 3: Detect The Unity Environment

Read `ProjectSettings/ProjectVersion.txt` and record the editor version, revision when present, and Unity generation.

Read `Packages/manifest.json` and `Packages/packages-lock.json` when present. Separate packages into Unity registry packages, embedded packages, Git packages, local file packages, scoped-registry packages, and unknown/custom packages.

Record packages relevant to render pipelines, input, networking, localization, addressables, entities/DOTS, tests, cinematics, animation, XR, multiplayer tools, dependency injection, async frameworks, and similar development workflows.

Do not dump the complete dependency list unless requested.

## Phase 4: Classify Key Systems

Classify the render pipeline from package dependencies, graphics settings, project documentation, and shader/material evidence. Use one of: Built-in Render Pipeline, Universal Render Pipeline, High Definition Render Pipeline, custom or mixed, unresolved.

Classify input as legacy Input Manager, Input System package, both, custom abstraction, or unresolved.

Detect networking from confirmed dependencies and first-party usage. Do not classify a project as multiplayer merely because a networking package exists.

Detect Unity Test Framework, EditMode tests, PlayMode tests, custom test assemblies, external test scripts, and CI test commands.

## Phase 5: Understand Project Structure

Inspect first-party directories under `Assets/`.

Ignore generated, imported, vendor, and cache directories where possible. Common vendor indicators include `Plugins`, `ThirdParty`, package names, publisher names, imported asset-store folders, and directories containing their own licenses or package manifests.

Identify primary game-code roots, editor-only code, tests, scenes, prefabs, ScriptableObjects, shaders, VFX, UI, networking, localization, addressable content, streaming assets, resources, plugins, and native libraries.

Do not assume directory names accurately represent architecture. Verify important conclusions against namespaces, assemblies, or representative files.

## Phase 6: Inspect Assemblies And Boundaries

Locate `.asmdef` and `.asmref` files.

For each important first-party assembly, record assembly name, approximate responsibility, major references, editor-only status, test status, platform restrictions, and unsafe-code setting when relevant.

Identify likely dependency direction. Flag observations such as circular conceptual dependencies, runtime assemblies depending on presentation-specific assemblies, large monolithic assemblies, editor code mixed into runtime folders, and test assemblies referencing unexpected production layers.

## Phase 7: Identify Scenes And Startup Flow

Determine scene information using the strongest available source:

1. A connected Unity MCP that can read Build Settings safely.
2. Serialized project settings.
3. Editor build-settings assets.
4. Documentation and scripts as fallback evidence.

Record enabled build scenes, likely boot/startup scene, menu or lobby scene, gameplay scenes, test/development scenes, and scene-loading system when identifiable.

Do not open, save, or modify scenes during onboarding.

## Phase 8: Identify Architecture And Conventions

Inspect a small, representative sample of first-party code. Do not read every script by default.

Look for MonoBehaviour-centric architecture, ScriptableObject architecture, service locator, dependency injection, event bus, MVC/MVP/MVVM, ECS, feature-based organization, state machines, command systems, data-oriented systems, custom update loops, async patterns, reactive frameworks, save-data architecture, and scene composition roots.

Classify each pattern as confirmed, likely, or uncertain.

Inspect existing code and formatting configuration for namespace style, private-field naming, serialized-field style, brace style, nullable-reference usage, async conventions, event naming, file organization, regions, comments, and XML documentation expectations.

Do not invent conventions from a single file unless no broader evidence exists.

## Phase 9: Detect Available Unity Tools

Map available tools to conceptual capabilities rather than coupling the skill to exact tool names.

Relevant capabilities include:

- `unity.connection.status`
- `unity.editor.version`
- `unity.console.read`
- `unity.scene.list`
- `unity.scene.inspect`
- `unity.buildsettings.read`
- `unity.gameobject.inspect`
- `unity.asset.search`
- `unity.package.read`
- `unity.tests.list`
- `unity.tests.run`
- `unity.playmode.read`
- `unity.profiler.read`

Do not invoke mutating tools during onboarding.

Do not enter Play Mode.

Do not run tests unless the user explicitly requested validation, or the project can run them safely and doing so is necessary to establish the current baseline.

## Phase 10: Generate The Project Context

Use `references/context-template.md`.

The document should normally contain:

1. Project summary
2. Confirmed environment
3. Important packages and frameworks
4. Directory structure
5. Assembly boundaries
6. Scenes and startup flow
7. Architecture
8. Coding conventions
9. Testing and validation
10. Available Unity tooling
11. Important constraints
12. Unknowns and confidence
13. Source files inspected
14. Last analyzed commit and date

Keep the main document short enough to be loaded frequently.

Avoid complete package dumps, inventories of every scene or script, speculative recommendations, generic Unity advice, copying README content verbatim, and information that can be rediscovered trivially.

## Updating An Existing Context Document

When `UnityProjectContext.md` already exists:

1. Read it before running the full inspection.
2. Preserve manually authored sections.
3. Validate claims that may have become stale.
4. Update changed facts.
5. Remove claims that are no longer supported.
6. Keep unresolved historical notes only when still useful.
7. Update the analyzed commit and date.
8. Summarize meaningful changes after editing.

Use explicit markers for generated sections when appropriate:

`<!-- unity-onboarding:generated:start -->`

`<!-- unity-onboarding:generated:end -->`

Do not overwrite text outside generated markers unless clearly obsolete and safe to update.

## Confidence And Evidence

Every important conclusion must be one of:

- **Confirmed:** directly supported by authoritative project configuration, code, documentation, or Editor data.
- **Likely:** supported by several indirect signals.
- **Unknown:** insufficient evidence.

For important claims, record one or more source paths.

## Safety Boundaries

During onboarding, do not:

- modify `.unity`, `.prefab`, `.asset`, `.mat`, `.controller`, or `.anim` files
- install, update, or remove packages
- change project settings
- enter Play Mode
- trigger a build
- reimport the project
- regenerate solution files
- delete generated directories
- fix warnings automatically
- reorganize folders
- rename assemblies or namespaces
- add dependencies
- create sample gameplay content
- expose credentials or secret values in generated documentation

If secrets are found, report their location without reproducing their values.

## Completion Criteria

Onboarding is complete when the Unity project root is verified, Unity version is known, relevant packages are summarized, render pipeline and input system are classified, important first-party directories are mapped, major assemblies are understood, scenes and startup flow are described as far as evidence permits, architectural and coding conventions are summarized, available Unity MCP capabilities are recorded, uncertainties are clearly marked, the context document is created or updated when appropriate, and no project assets were modified.

## Final Response

Return a concise summary containing:

- Unity version
- render pipeline
- important frameworks
- main architectural pattern
- startup scene or flow
- testing support
- available MCP/tooling
- context-document path
- important unknowns or risks

Do not repeat the complete context document in the response unless requested.

Referenced files: 1