version: "1.0.3" name: unity-perception description: Read-only scene, project and script analysis for AI context

Before calling any skill in this module: if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via GET /skills/recommend?includeSchema=true) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

Triggers

• Gathering context before editing
• Understanding unfamiliar scene/project
• Auditing structure without changes
• 编辑前收集上下文、理解陌生场景或项目、在不改动的前提下审查结构

Unity Perception Skills

Use this module for read-only scene and project analysis.

Operating Mode

• Approval / Auto / Bypass: 本模块 18 个 skill 里的 17 个纯读 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）都标 Mode = SkillMode.SemiAuto 且 ReadOnly = true，三档模式下直接执行无需 grant。
• 特别说明：scene_export_report 写 markdown 文件到磁盘（Operation = Analyze | Execute，标 MutatesAssets = true），因此不是 SemiAuto——它走默认 SkillMode.FullAuto，Approval 模式下需要 grant 才能执行。
• 本模块不含 Delete / PlayMode / Reload / RiskLevel=high 类 skill —— 没有 IsForbiddenInSemi 拦截。

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

Scene Snapshots and Exports

Project and Script Analysis

Spatial and Material Queries

High-Frequency Skill Differences

scene_summarize vs scene_analyze vs scene_health_check

scene_context vs hierarchy_describe

scene_dependency_analyze vs script_dependency_graph

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

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.