Update to Unity Essentials

{
  "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.",
  "included_files": [
    {
      "relative_path": "references/context-template.md",
      "size_in_bytes": 1661
    }
  ],
  "name": "unity-project-onboarding",
  "skill_md_contents": "---\nname: unity-project-onboarding\ndescription: 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.\n---\n\n# Unity Project Onboarding\n\nUnderstand the Unity project before making substantial changes.\n\nThis 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.\n\n## Surface Limits\n\nIf 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.\n\nIf Codex has a workspace or local files available, verify the project root from actual files before producing findings.\n\n## Primary outcome\n\nCreate or update:\n\n`Docs/AI/UnityProjectContext.md`\n\nIf the project already uses another documentation location, prefer that location instead of creating a competing structure.\n\nDo not create the document when the user only requested a quick explanation. In that case, return the findings directly.\n\n## Core Principles\n\n1. Inspect before modifying.\n2. Prefer repository evidence over assumptions.\n3. Separate confirmed facts from inferred conclusions.\n4. Do not require a Unity MCP.\n5. Use an available MCP only when it provides useful additional evidence.\n6. Do not open or modify scenes merely to collect information.\n7. Keep the generated context concise and useful for future tasks.\n8. Preserve useful manually written documentation.\n9. Never report a framework as installed solely because its name appears in generated or cached files.\n10. Treat `Library/`, `Temp/`, `Logs/`, `obj/`, and build output as generated directories unless the project explicitly documents otherwise.\n\n## MCP Policy\n\nDuring onboarding, detect whether the project already has a Unity MCP provider before suggesting a new one.\n\nCheck:\n\n- `Packages/manifest.json`\n- `Packages/packages-lock.json`\n- embedded packages under `Packages/`\n- project MCP client config files\n- currently available Codex MCP tools\n\nRecord existing MCP/tooling as `available`, `unavailable`, or `unverified`.\n\nDo 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.\n\n## Phase 1: Verify The Project\n\nConfirm that the current repository is a Unity project by looking for:\n\n- `Assets/`\n- `Packages/manifest.json`\n- `ProjectSettings/ProjectVersion.txt`\n\nIf 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.\n\nRecord the resolved Unity project root.\n\n## Phase 2: Read Existing Guidance\n\nBefore analyzing implementation details, locate existing project instructions.\n\nCheck for:\n\n- `AGENTS.md`\n- `CLAUDE.md`\n- `README.md`\n- `CONTRIBUTING.md`\n- files under `Docs/`\n- files under `.github/`\n- existing AI context or architecture documentation\n\nExtract naming conventions, folder conventions, architectural rules, testing requirements, supported platforms, prohibited changes, package-management rules, and build instructions.\n\nProject-specific instructions override generic recommendations in this skill.\n\n## Phase 3: Detect The Unity Environment\n\nRead `ProjectSettings/ProjectVersion.txt` and record the editor version, revision when present, and Unity generation.\n\nRead `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.\n\nRecord 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.\n\nDo not dump the complete dependency list unless requested.\n\n## Phase 4: Classify Key Systems\n\nClassify 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.\n\nClassify input as legacy Input Manager, Input System package, both, custom abstraction, or unresolved.\n\nDetect networking from confirmed dependencies and first-party usage. Do not classify a project as multiplayer merely because a networking package exists.\n\nDetect Unity Test Framework, EditMode tests, PlayMode tests, custom test assemblies, external test scripts, and CI test commands.\n\n## Phase 5: Understand Project Structure\n\nInspect first-party directories under `Assets/`.\n\nIgnore 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.\n\nIdentify 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.\n\nDo not assume directory names accurately represent architecture. Verify important conclusions against namespaces, assemblies, or representative files.\n\n## Phase 6: Inspect Assemblies And Boundaries\n\nLocate `.asmdef` and `.asmref` files.\n\nFor 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.\n\nIdentify 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.\n\n## Phase 7: Identify Scenes And Startup Flow\n\nDetermine scene information using the strongest available source:\n\n1. A connected Unity MCP that can read Build Settings safely.\n2. Serialized project settings.\n3. Editor build-settings assets.\n4. Documentation and scripts as fallback evidence.\n\nRecord enabled build scenes, likely boot/startup scene, menu or lobby scene, gameplay scenes, test/development scenes, and scene-loading system when identifiable.\n\nDo not open, save, or modify scenes during onboarding.\n\n## Phase 8: Identify Architecture And Conventions\n\nInspect a small, representative sample of first-party code. Do not read every script by default.\n\nLook 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.\n\nClassify each pattern as confirmed, likely, or uncertain.\n\nInspect 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.\n\nDo not invent conventions from a single file unless no broader evidence exists.\n\n## Phase 9: Detect Available Unity Tools\n\nMap available tools to conceptual capabilities rather than coupling the skill to exact tool names.\n\nRelevant capabilities include:\n\n- `unity.connection.status`\n- `unity.editor.version`\n- `unity.console.read`\n- `unity.scene.list`\n- `unity.scene.inspect`\n- `unity.buildsettings.read`\n- `unity.gameobject.inspect`\n- `unity.asset.search`\n- `unity.package.read`\n- `unity.tests.list`\n- `unity.tests.run`\n- `unity.playmode.read`\n- `unity.profiler.read`\n\nDo not invoke mutating tools during onboarding.\n\nDo not enter Play Mode.\n\nDo 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.\n\n## Phase 10: Generate The Project Context\n\nUse `references/context-template.md`.\n\nThe document should normally contain:\n\n1. Project summary\n2. Confirmed environment\n3. Important packages and frameworks\n4. Directory structure\n5. Assembly boundaries\n6. Scenes and startup flow\n7. Architecture\n8. Coding conventions\n9. Testing and validation\n10. Available Unity tooling\n11. Important constraints\n12. Unknowns and confidence\n13. Source files inspected\n14. Last analyzed commit and date\n\nKeep the main document short enough to be loaded frequently.\n\nAvoid 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.\n\n## Updating An Existing Context Document\n\nWhen `UnityProjectContext.md` already exists:\n\n1. Read it before running the full inspection.\n2. Preserve manually authored sections.\n3. Validate claims that may have become stale.\n4. Update changed facts.\n5. Remove claims that are no longer supported.\n6. Keep unresolved historical notes only when still useful.\n7. Update the analyzed commit and date.\n8. Summarize meaningful changes after editing.\n\nUse explicit markers for generated sections when appropriate:\n\n`<!-- unity-onboarding:generated:start -->`\n\n`<!-- unity-onboarding:generated:end -->`\n\nDo not overwrite text outside generated markers unless clearly obsolete and safe to update.\n\n## Confidence And Evidence\n\nEvery important conclusion must be one of:\n\n- **Confirmed:** directly supported by authoritative project configuration, code, documentation, or Editor data.\n- **Likely:** supported by several indirect signals.\n- **Unknown:** insufficient evidence.\n\nFor important claims, record one or more source paths.\n\n## Safety Boundaries\n\nDuring onboarding, do not:\n\n- modify `.unity`, `.prefab`, `.asset`, `.mat`, `.controller`, or `.anim` files\n- install, update, or remove packages\n- change project settings\n- enter Play Mode\n- trigger a build\n- reimport the project\n- regenerate solution files\n- delete generated directories\n- fix warnings automatically\n- reorganize folders\n- rename assemblies or namespaces\n- add dependencies\n- create sample gameplay content\n- expose credentials or secret values in generated documentation\n\nIf secrets are found, report their location without reproducing their values.\n\n## Completion Criteria\n\nOnboarding 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.\n\n## Final Response\n\nReturn a concise summary containing:\n\n- Unity version\n- render pipeline\n- important frameworks\n- main architectural pattern\n- startup scene or flow\n- testing support\n- available MCP/tooling\n- context-document path\n- important unknowns or risks\n\nDo not repeat the complete context document in the response unless requested.\n"
}