Unity Perception Skills
Overview
Use this module for read-only scene and project analysis. It is available in Semi-Auto by default.
Common Mistakes
DO NOT (common hallucinations):
perception_analyze, perception_scan, and perception_describe do not existscene_context is not editor_get_context: it exports hierarchy/components/references, while editor context focuses on current editor statescene_analyze, scene_health_check, scene_contract_validate, scene_component_stats, scene_find_hotspots, and project_stack_detect belong to this module even if the prefix looks like scene_* or project_*
Routing:
- Current selection/play-mode/editor state ->
editor_get_context
- Object search by name/path ->
scene_find_objects or gameobject_find
- Script dependency closure ->
script_dependency_graph
Skills
Scene Health and Summary
| Skill |
Use |
Key parameters |
scene_analyze |
Combined scene + project analysis |
topComponentsLimit?, issueLimit?, deepHierarchyThreshold?, largeChildCountThreshold? |
scene_health_check |
Read-only health report |
issueLimit?, deepHierarchyThreshold?, largeChildCountThreshold? |
scene_summarize |
Structured scene summary |
includeComponentStats?, topComponentsLimit? |
scene_component_stats |
Component and facility stats |
topComponentsLimit? |
scene_find_hotspots |
Deep hierarchy / large group / empty node hotspots |
thresholds + maxResults? |
scene_tag_layer_stats |
Tag/layer usage |
none |
scene_performance_hints |
Prioritized optimization hints |
none |
Scene Snapshots and Exports
| Skill |
Use |
Key parameters |
scene_diff |
Capture or compare lightweight snapshots |
snapshotJson? |
hierarchy_describe |
Return text hierarchy tree |
maxDepth?, includeInactive?, maxItemsPerLevel? |
scene_context |
Export hierarchy, components, references |
maxDepth?, maxObjects?, rootPath?, includeValues?, includeReferences?, includeCodeDeps? |
scene_export_report |
Save markdown scene report |
savePath?, maxDepth?, maxObjects? |
scene_dependency_analyze |
Analyze impact / dependency graph in-scene |
targetPath?, savePath? |
Project and Script Analysis
| Skill |
Use |
Key parameters |
project_stack_detect |
Detect pipeline, input, UI, packages, tests, folders |
none |
script_analyze |
Analyze one MonoBehaviour / ScriptableObject / user class by class name |
scriptName, includePrivate? |
script_dependency_graph |
N-hop dependency closure for one script class name |
scriptName, maxHops?, includeDetails? |
Spatial and Material Queries
| Skill |
Use |
Key parameters |
scene_spatial_query |
Find objects near a point or object |
x/y/z?, radius?, nearObject?, componentFilter?, maxResults? |
scene_materials |
Summarize scene materials and shaders |
includeProperties? |
scene_contract_validate |
Validate default roots/tags/layers/UI EventSystem conventions |
requiredRootsJson?, requiredTagsJson?, requiredLayersJson?, requireEventSystemForUi? |
High-Frequency Skill Differences
scene_summarize vs scene_analyze vs scene_health_check
| Skill |
Best for |
Typical output focus |
scene_summarize |
Fast overview |
object counts, hierarchy depth, top components |
scene_analyze |
Broad diagnosis |
summary + findings + warnings + recommendations + next-skill hints |
scene_health_check |
Hygiene / red flags |
missing scripts, duplicate names, deep hierarchy, empty nodes, hotspot-style findings |
scene_context vs hierarchy_describe
| Skill |
Best for |
Output style |
hierarchy_describe |
Human-readable tree |
text tree, lightweight |
scene_context |
AI coding context |
structured hierarchy + components + references + optional code dependencies |
scene_dependency_analyze vs script_dependency_graph
| Skill |
Scope |
Use when |
scene_dependency_analyze |
Scene object references |
ask "删掉/禁用这个对象会影响谁" |
script_dependency_graph |
Script class dependency closure |
ask "要改这个功能先看哪些脚本" |
Key Return Shapes
scene_summarize
Returns sceneName, stats, and optional topComponents.
scene_analyze
Returns summary, stats, findings, warnings, recommendations, and suggestedNextSkills.
scene_health_check
Returns summary, findings, hotspots, and suggestedNextSkills.
scene_context
Returns a structured export with objects, references, and optional codeDependencies. Use it when another AI step needs full scene context, not just a human summary.
High-frequency options:
rootPath to export only one subtreeincludeValues=true when serialized field values matterincludeCodeDeps=true when AI needs a rough scene-to-code dependency picture
scene_export_report
Writes a markdown artifact to disk and returns savedTo, object/script/reference counts, and success state. Prefer this when the user wants a durable report file.
Defaults:
savePath = "Assets/Docs/SceneReport.md"maxDepth = 10maxObjects = 500
When to Use Which Skill
| Need |
Best first skill |
| Quick scene overview |
scene_summarize |
| Full diagnosis |
scene_analyze |
| Suspicious hierarchy or clutter |
scene_find_hotspots |
| Safe-to-delete / impact question |
scene_dependency_analyze |
| AI coding context export |
scene_context |
| Script reading order |
script_dependency_graph |
| Render/input/UI stack detection |
project_stack_detect |
RunCommand Examples
Recipe path rule: ../../recipes/perception/<command>.md
See ../../recipes/perception/README.md for the full command index and per-command C# templates.
1---2name: unity-perception3description: Use when users want to get a summary, overview, dependency report, or export of the current scene state.4---56# Unity Perception Skills78## Overview910Use this module for read-only scene and project analysis. It is available in Semi-Auto by default.1112## Common Mistakes131415**DO NOT** (common hallucinations):16- `perception_analyze`, `perception_scan`, and `perception_describe` do not exist17- `scene_context` is not `editor_get_context`: it exports hierarchy/components/references, while editor context focuses on current editor state18- `scene_analyze`, `scene_health_check`, `scene_contract_validate`, `scene_component_stats`, `scene_find_hotspots`, and `project_stack_detect` belong to this module even if the prefix looks like `scene_*` or `project_*`1920**Routing**:21- Current selection/play-mode/editor state -> `editor_get_context`22- Object search by name/path -> `scene_find_objects` or `gameobject_find`23- Script dependency closure -> `script_dependency_graph`2425## Skills2627### Scene Health and Summary2829| Skill | Use | Key parameters |30|-------|-----|----------------|31| `scene_analyze` | Combined scene + project analysis | `topComponentsLimit?`, `issueLimit?`, `deepHierarchyThreshold?`, `largeChildCountThreshold?` |32| `scene_health_check` | Read-only health report | `issueLimit?`, `deepHierarchyThreshold?`, `largeChildCountThreshold?` |33| `scene_summarize` | Structured scene summary | `includeComponentStats?`, `topComponentsLimit?` |34| `scene_component_stats` | Component and facility stats | `topComponentsLimit?` |35| `scene_find_hotspots` | Deep hierarchy / large group / empty node hotspots | thresholds + `maxResults?` |36| `scene_tag_layer_stats` | Tag/layer usage | none |37| `scene_performance_hints` | Prioritized optimization hints | none |3839### Scene Snapshots and Exports4041| Skill | Use | Key parameters |42|-------|-----|----------------|43| `scene_diff` | Capture or compare lightweight snapshots | `snapshotJson?` |44| `hierarchy_describe` | Return text hierarchy tree | `maxDepth?`, `includeInactive?`, `maxItemsPerLevel?` |45| `scene_context` | Export hierarchy, components, references | `maxDepth?`, `maxObjects?`, `rootPath?`, `includeValues?`, `includeReferences?`, `includeCodeDeps?` |46| `scene_export_report` | Save markdown scene report | `savePath?`, `maxDepth?`, `maxObjects?` |47| `scene_dependency_analyze` | Analyze impact / dependency graph in-scene | `targetPath?`, `savePath?` |4849### Project and Script Analysis5051| Skill | Use | Key parameters |52|-------|-----|----------------|53| `project_stack_detect` | Detect pipeline, input, UI, packages, tests, folders | none |54| `script_analyze` | Analyze one MonoBehaviour / ScriptableObject / user class by class name | `scriptName`, `includePrivate?` |55| `script_dependency_graph` | N-hop dependency closure for one script class name | `scriptName`, `maxHops?`, `includeDetails?` |5657### Spatial and Material Queries5859| Skill | Use | Key parameters |60|-------|-----|----------------|61| `scene_spatial_query` | Find objects near a point or object | `x/y/z?`, `radius?`, `nearObject?`, `componentFilter?`, `maxResults?` |62| `scene_materials` | Summarize scene materials and shaders | `includeProperties?` |63| `scene_contract_validate` | Validate default roots/tags/layers/UI EventSystem conventions | `requiredRootsJson?`, `requiredTagsJson?`, `requiredLayersJson?`, `requireEventSystemForUi?` |6465## High-Frequency Skill Differences6667### `scene_summarize` vs `scene_analyze` vs `scene_health_check`6869| Skill | Best for | Typical output focus |70|-------|----------|----------------------|71| `scene_summarize` | Fast overview | object counts, hierarchy depth, top components |72| `scene_analyze` | Broad diagnosis | summary + findings + warnings + recommendations + next-skill hints |73| `scene_health_check` | Hygiene / red flags | missing scripts, duplicate names, deep hierarchy, empty nodes, hotspot-style findings |7475### `scene_context` vs `hierarchy_describe`7677| Skill | Best for | Output style |78|-------|----------|-------------|79| `hierarchy_describe` | Human-readable tree | text tree, lightweight |80| `scene_context` | AI coding context | structured hierarchy + components + references + optional code dependencies |8182### `scene_dependency_analyze` vs `script_dependency_graph`8384| Skill | Scope | Use when |85|-------|-------|----------|86| `scene_dependency_analyze` | Scene object references | ask "删掉/禁用这个对象会影响谁" |87| `script_dependency_graph` | Script class dependency closure | ask "要改这个功能先看哪些脚本" |8889## Key Return Shapes9091### `scene_summarize`9293Returns `sceneName`, `stats`, and optional `topComponents`.9495### `scene_analyze`9697Returns `summary`, `stats`, `findings`, `warnings`, `recommendations`, and `suggestedNextSkills`.9899### `scene_health_check`100101Returns `summary`, `findings`, `hotspots`, and `suggestedNextSkills`.102103### `scene_context`104105Returns a structured export with `objects`, `references`, and optional `codeDependencies`. Use it when another AI step needs full scene context, not just a human summary.106107High-frequency options:108- `rootPath` to export only one subtree109- `includeValues=true` when serialized field values matter110- `includeCodeDeps=true` when AI needs a rough scene-to-code dependency picture111112### `scene_export_report`113114Writes a markdown artifact to disk and returns `savedTo`, object/script/reference counts, and success state. Prefer this when the user wants a durable report file.115116Defaults:117- `savePath = "Assets/Docs/SceneReport.md"`118- `maxDepth = 10`119- `maxObjects = 500`120121## When to Use Which Skill122123| Need | Best first skill |124|------|------------------|125| Quick scene overview | `scene_summarize` |126| Full diagnosis | `scene_analyze` |127| Suspicious hierarchy or clutter | `scene_find_hotspots` |128| Safe-to-delete / impact question | `scene_dependency_analyze` |129| AI coding context export | `scene_context` |130| Script reading order | `script_dependency_graph` |131| Render/input/UI stack detection | `project_stack_detect` |132133## RunCommand Examples134135Recipe path rule: `../../recipes/perception/<command>.md`136137See [../../recipes/perception/README.md](../../recipes/perception/README.md) for the full command index and per-command C# templates.138
batihandev