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
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: directory does not exist or
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
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
- Read , , and any docs in folder
- Read to understand all included packages
- List all scenes:
- List all script folders and assembly definitions:
- List all prefab folders: find directories containing files
- Identify the project's Unity version from
ProjectSettings/ProjectVersion.txt
- If Unity MCP is connected, optionally inspect scene hierarchies, prefab components, and project settings programmatically for richer data
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 ()
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 ()
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 ()
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 ()
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 ()
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
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
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)
- Read and
- 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
- Check git status for recently modified files if helpful
- Update only the affected sub-documents
- 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.
- Update if new docs were added or removed
- Update and the documented lists in
Do NOT rewrite docs that haven't changed.
Instructions for Ingestion (Mode 4)
- Check if exists — if not, skip (no docs to ingest)
- Read to get the document map and quick context
- 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
- "How does the ball system work?" → read
- "What scenes are there?" → read
- General project questions → read and
- 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 at the top of each sub-doc. This helps identify docs that may need refresh.
- Dates: Use only the date in fields — no parenthetical annotations.
File Naming Convention
- Use lowercase kebab-case for all filenames: ,
- Prefix flow/index files with underscore: ,
- Match scene/system names but in kebab-case: →