Unity Perception Skills

Use this module for read-only scene and project analysis. It is available in Semi-Auto by default.

Guardrails

Mode: Semi-Auto

DO NOT (common hallucinations):

• perception_analyze, perception_scan, and perception_describe do not exist
• scene_context is not editor_get_context: it exports hierarchy/components/references, while editor context focuses on current editor state
• 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_*

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 "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:

• rootPath to export only one subtree
• includeValues=true when serialized field values matter
• includeCodeDeps=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 = 10
• maxObjects = 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.