---
name: hz-unity-project-analyzer
license: Apache-2.0
description: Analyzes, documents, and maintains a living `.agent-docs/` knowledge base for Unity projects targeting Meta VR and Horizon OS. Use when the user asks to scan project structure, explain how a Unity system works, or update project docs after structural changes.
---

# 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:
```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

#### 3f. Scripts Reference (`.agent-docs/scripts/`)
Scripts are self-documenting through code. Here, document **usage context only**:
- Organize by system or feature area
- For each script: purpose, how to use it, which prefab/scene it belongs to
- Do NOT duplicate code or describe implementation details

### Step 4: Build the Index

Create or update `.agent-docs/index.md` as the main entry point:

```markdown
# [Project Name] — Agent Documentation

> Auto-generated project knowledge base for AI agent comprehension.
> Last updated: YYYY-MM-DD

## Quick Context
[2-3 sentence project summary]

## Document Map
- [Project Overview](project-overview.md)
- Scenes
  - [Scene Flow](<scenes/_flow.md>)
  - [SceneName](<scenes/scene-name.md>)
  - ...
- Systems
  - [SystemName](<systems/system-name.md>)
  - ...
- Prefabs
  - [PrefabGroup](<prefabs/group-name.md>)
  - ...
- Assets
  - [AssetGroup](<assets/group-name.md>)
  - ...
- Scripts
  - [ScriptArea](<scripts/area-name.md>)
  - ...

## Runtime Flow
[Brief description of app lifecycle from launch to gameplay]
```

### Step 5: Create Config

Create `.agent-docs/_config.md`:
```markdown
---
last_full_scan: YYYY-MM-DD
last_update: YYYY-MM-DD
documented_systems:
  - system-name-1
  - system-name-2
documented_scenes:
  - scene-name-1
  - scene-name-2
documented_prefab_groups:
  - group-name-1
  - group-name-2
---
```

---

## Instructions for Incremental Update (Mode 2)

1. Read `.agent-docs/_config.md` and `.agent-docs/index.md`
2. Identify what changed:
   - If the AI agent just made changes: update only the docs affected by those changes
   - If the user asks to update: compare current project state against documented state
     - Check for new/removed/renamed scenes, scripts, prefabs
     - Check for new packages in `Packages/manifest.json`
     - Check git status for recently modified files if helpful
3. Update only the affected sub-documents
4. **Clean up stale references:** If a script, prefab, or asset was deleted or renamed, remove or update references to it in the affected docs. Do not leave broken references.
5. Update `.agent-docs/index.md` if new docs were added or removed
6. Update `last_update` and the documented lists in `.agent-docs/_config.md`

Do NOT rewrite docs that haven't changed.

---

## Instructions for Ingestion (Mode 4)

1. Check if `.agent-docs/index.md` exists — if not, skip (no docs to ingest)
2. Read `.agent-docs/index.md` to get the document map and quick context
3. Based on the user's question, read **only** the sub-docs relevant to what they are asking about. For example:
   - "What does this project do?" → read `project-overview.md`
   - "How does the ball system work?" → read `systems/balls.md`
   - "What scenes are there?" → read `scenes/_flow.md`
   - General project questions → read `project-overview.md` and `scenes/_flow.md`
4. Do NOT eagerly read all sub-docs — read on-demand to keep context focused

---

## Document Writing Guidelines

- **Audience:** AI agents first. Be explicit, structured, and unambiguous.
- **Size:** Keep each sub-doc concise. Prefer structured lists over paragraphs. Target under 200 lines per doc.
- **Cross-references:** Use relative markdown links between docs when there's an actual dependency or relationship.
- **Diagrams:** Use mermaid when it clarifies flow or architecture better than prose. Skip when prose is clearer.
- **Third-party packages:** Document how the project uses them. Do not document their internals.
- **Scripts:** Document purpose and usage, not implementation. The code is self-documenting.
- **Prefabs:** Document nested hierarchies. Note important inspector configuration.
- **Source control:** One concept per file. Use descriptive filenames. Avoid large monolithic docs.
- **Staleness:** Include `Last updated: YYYY-MM-DD` at the top of each sub-doc. This helps identify docs that may need refresh.
- **Dates:** Use only the date in `Last updated` fields — no parenthetical annotations.

## File Naming Convention

- Use lowercase kebab-case for all filenames: `player-controller.md`, `main-menu.md`
- Prefix flow/index files with underscore: `_flow.md`, `_config.md`
- Match scene/system names but in kebab-case: `Startup.unity` → `startup.md`