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 p

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 31 — file references are metadata, not package contents.

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/perform

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 39 — file references are metadata, not package contents.

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

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 37 — file references are metadata, not package contents.

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: co

Preview of the first 4,000 characters. Read full instructions →

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/testi

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 35 — file references are metadata, not package contents.

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 ge

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.