Hz Unity Project Analyzer

Unity Project Analyzer

Analyze, document, and maintain a living knowledge base of a Unity project's structure, optimized for AI agent comprehension. Output lives in .agent-docs/ as source-control-friendly markdown files.

Modes of Operation

This skill operates in four modes. Determine which mode to use based on context:

Mode 1: First-Time Full Scan

Trigger: .agent-docs/ directory does not exist or .agent-docs/index.md does not exist.

Mode 2: Incremental Update

Trigger: User asks to update docs, or AI agent has made structural changes (new scenes, scripts, prefabs, systems). Default update mode.

Important: Incremental updates are part of implementation, not a separate step. When creating or modifying scripts, prefabs, or assets, update the corresponding .agent-docs/ files in the same pass before moving on to the next task.

Mode 3: Full Rescan

Trigger: User explicitly requests a full rescan (e.g., "rescan project", "full project analysis").

Mode 4: Ingestion

Trigger: User asks about the project structure or how a system/feature works (e.g., "what does this project do", "how does the ball system work", "project structure", "load project analysis"). Only use this mode when .agent-docs/ exists. This mode is read-only — do not modify docs.

Instructions for Full Scan (Mode 1) and Full Rescan (Mode 3)

Step 1: Gather Project Overview

1. Read README.md, CHANGELOG.md, and any docs in Documentation/ folder
2. Read Packages/manifest.json to understand all included packages
3. List all scenes: Assets/**/*.unity
4. List all script folders and assembly definitions: Assets/**/*.asmdef
5. List all prefab folders: find directories containing .prefab files
6. Identify the project's Unity version from ProjectSettings/ProjectVersion.txt
7. If an Editor is reachable (unity status --format json shows state ready), inspect it live for richer data than the files alone give — unity command get_scene_hierarchy, find_assets, package_list --scope installed, and the get_*_settings commands (get_player_settings, get_quality_settings, get_graphics_settings). See the unity-cli skill.
8. If a headset is attached, record the test-device baseline — metavr device list and metavr device info <id> (OS version, form factor) — so later findings can cite the hardware they were observed on.

Step 2: Ask Clarifying Questions

Before documenting, ask the user about anything that is not clear from the code or docs alone. Examples:

• "I see scenes named X, Y, Z — which is the main entry point?"
• "There's a folder called [name] with assets I can't determine the purpose of — what is it for?"
• "I see multiple networking approaches — which is the primary one?"

Only ask about genuinely ambiguous items. If something is clear from naming, folder structure, or code inspection, document it directly.

Step 3: Analyze and Document

For each category below, create or update the corresponding sub-document:

3a. Project Overview (.agent-docs/project-overview.md)

• Project name, description, Unity version
• Target platform(s)
• High-level architecture summary
• Key third-party packages and how they are used in this project (surface-level only — no internals)

3b. Scene Flow (.agent-docs/scenes/)

Create one file per scene (e.g., .agent-docs/scenes/startup.md).

For each scene document:

• Purpose and role in the project
• Key GameObjects and their purpose
• Which scripts/prefabs are used
• Scene transitions (what loads this scene, what does this scene load)
• Whether it's part of the main runtime flow, a test scene, or an example

Create a scene flow diagram in .agent-docs/scenes/_flow.md using mermaid:

graph LR
    Startup --> MainMenu --> Gameplay

3c. Systems (.agent-docs/systems/)

Identify logical systems (networking, UI, audio, input, gameplay, etc.) and create one file per system.

For each system document:

• Purpose and responsibility
• Key scripts (with file paths) and their roles — focus on how to use them, not implementation
• Key prefabs the system uses
• Dependencies on other systems
• Cross-reference related scenes and other system docs with relative links

3d. Prefabs (.agent-docs/prefabs/)

Group or document individually based on clarity:

• If a folder of prefabs is self-explanatory by naming → group doc (e.g., .agent-docs/prefabs/ui-elements.md)
• If individual prefabs have non-obvious purpose → document individually (e.g., .agent-docs/prefabs/player-rig.md)

For each prefab/group:

• Purpose and when to use it
• Nested prefab hierarchy (document nested prefabs and variants)
• Key components attached
• Which scenes use it
• Configuration notes (important inspector values, required references)

3e. Assets (.agent-docs/assets/)

Document non-script, non-prefab assets adaptively:

• Materials, shaders, textures, audio, animations, scriptable objects
• Group when folder naming is clear; document individually when purpose is non-obvious
• Focus on: what is it, what is it for, how/where is it used