Unity Perception Skills
unity-perception
Read-only scene/project/script analysis for AI coding context — scene health/summary/hotspots, hierarchy describe, stats, dependency & impact graph, project stack, scene context export. Exact signatures via GET /skills/schema.
SKILL.md
Full skill instructions
Unity Perception Skills
Use this module for read-only scene and project analysis.
Operating Mode
- Approval / Auto / Bypass: 本模块所有 skill（
scene_analyze/scene_summarize/scene_health_check/scene_component_stats/scene_find_hotspots/scene_tag_layer_stats/scene_performance_hints/scene_diff/hierarchy_describe/scene_context/scene_dependency_analyze/scene_spatial_query/scene_materials/scene_contract_validate/project_stack_detect/script_analyze/script_dependency_graph/scene_export_report）都标Mode = SkillMode.SemiAuto，三档模式下直接执行无需 grant。其中前 17 个同时标ReadOnly = true。 - 特别说明：
scene_export_report写 markdown 文件到磁盘（Operation = Analyze | Execute，未标ReadOnly），但仍标了SkillMode.SemiAuto，Approval 模式可直接执行。 - 本模块不含 Delete / PlayMode / Reload / RiskLevel=high 类 skill —— 没有
IsForbiddenInSemi拦截。
DO NOT (common hallucinations):
perception_analyze,perception_scan, andperception_describedo not existscene_contextis noteditor_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, andproject_stack_detectbelong to this module even if the prefix looks likescene_*orproject_*
Routing:
- Current selection/play-mode/editor state ->
editor_get_context - Object search by name/path ->
scene_find_objectsorgameobject_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 "who depends on this object if I delete or disable it" |
script_dependency_graph | Script class dependency closure | ask "which scripts do I have to touch to change this feature" |
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:
rootPathto export only one subtreeincludeValues=truewhen serialized field values matterincludeCodeDeps=truewhen 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 |
Minimal Example
import unity_skills
summary = unity_skills.call_skill("scene_summarize", includeComponentStats=True)
health = unity_skills.call_skill("scene_health_check", issueLimit=50)
context = unity_skills.call_skill("scene_context", maxDepth=6, maxObjects=120)
report = unity_skills.call_skill("scene_export_report", savePath="Assets/Docs/SceneReport.md")
Exact Signatures
Exact names, parameters, defaults, and returns are defined by GET /skills/schema or unity_skills.get_skill_schema(), not by this file.