unity-perception
Read-only scene, project and script analysis for AI context
How do I install this agent skill?
npx skills add https://github.com/besty0728/unity-skills --skill unity-perceptionIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a suite of tools for Unity scene and project analysis, including auditing hierarchy structure, script dependencies, and project hygiene. It is primarily read-only but supports generating markdown reports within the project directory.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- Runlayerpass
1 file scanned · No issues
What does this agent skill do?
Unity Perception Skills
Read-only analysis of the open scene, the project and scripts. Parameters come from the schema (GET /skills/schema?category=Perception&wire=v2); execution and dryRun rules: root SKILL.md.
When to use
- Gathering context before editing an unfamiliar scene or project
- Auditing scene structure, hygiene or hotspots without changing anything
- Checking what depends on an object or script before a change
- Exporting structured scene context for another AI step
Rules
- 17 skills are
SemiAutoand run in every mode without a grant; 16 of them are pure reads. scene_dependency_analyzeisSemiAutobut not read-only: passingsavePathwrites a markdown file and imports it as an asset. WithoutsavePathit returnsanalysisandmarkdownin the response and writes nothing. PasssavePathonly when the user asked for a file; the response then names it insavedTo.scene_export_reportwrites a markdown file (defaultAssets/Docs/SceneReport.md) and isFullAuto: under Approval it needs a grant.- No skill here deletes, enters Play Mode or triggers a reload.
Pitfalls
scene_contextexports hierarchy, components and references for AI coding. It is noteditor_get_context, which reports the current editor state.scene_contextmaxObjectsdefaults to 200; userootPathto export one subtree.
Routing
- Current selection, Play Mode or editor state →
editor_get_context. - Object search by name or path →
scene_find_objectsorgameobject_find. - Script dependency closure →
script_dependency_graph.
Choosing between similar skills
| Need | Use | Why |
|---|---|---|
| Quick overview | scene_summarize | Object counts, depth, top components |
| Broad diagnosis | scene_analyze | Summary, findings, warnings, recommendations, next-skill hints |
| Hygiene and red flags | scene_health_check | Missing scripts, duplicate names, deep hierarchy, empty nodes |
| Human-readable tree | hierarchy_describe | Lightweight text tree |
| Context for another AI step | scene_context | Structured hierarchy, components, references, optional code dependencies |
| What depends on this object | scene_dependency_analyze | Scene object references, for deletion or disabling |
| Which scripts a feature touches | script_dependency_graph | Script class dependency closure |
| Render, input and UI stack | project_stack_detect | Pipeline and package detection |
Key return shapes
scene_summarize:sceneName,stats, optionaltopComponents.scene_analyze:summary,stats,findings,warnings,recommendations,suggestedNextSkills.scene_health_check:summary,findings,hotspots,suggestedNextSkills.scene_context:objects,references, optionalcodeDependencies. SetincludeValues=truewhen serialized field values matter, andincludeCodeDeps=truefor a rough scene-to-code picture.scene_export_report:savedTo, object, script and reference counts, success.
DO NOT (common hallucinations):
perception_analyze,perception_scanandperception_describedo not exist.scene_analyze,scene_health_check,scene_contract_validate,scene_component_stats,scene_find_hotspotsandproject_stack_detectbelong to this module, even thoughproject_*orscene_*prefixes suggest otherwise.
Skills
scene_analyze
Combined scene and project analysis. Parameters: topComponentsLimit?, issueLimit?, deepHierarchyThreshold?, largeChildCountThreshold?
scene_health_check
Read-only health report. Parameters: issueLimit?, deepHierarchyThreshold?, largeChildCountThreshold?
scene_summarize
Structured scene summary. Parameters: includeComponentStats?, topComponentsLimit?
scene_component_stats
Component and facility stats. Parameters: topComponentsLimit?
scene_find_hotspots
Deep hierarchy, large group and empty node hotspots. Parameters: thresholds, maxResults?
scene_tag_layer_stats
Tag and layer usage. Parameters: none.
scene_performance_hints
Prioritized optimization hints. Parameters: none.
scene_diff
Capture or compare lightweight snapshots. Parameters: snapshotJson?
hierarchy_describe
Text hierarchy tree. Parameters: maxDepth?, includeInactive?, maxItemsPerLevel?
scene_context
Export hierarchy, components, references. Parameters: maxDepth?, maxObjects?, rootPath?, includeValues?, includeReferences?, includeCodeDeps?
scene_export_report
Save a markdown scene report. Parameters: savePath?, maxDepth?, maxObjects?
scene_dependency_analyze
Impact and dependency graph within the scene. Parameters: targetPath?, savePath? (writes a file)
project_stack_detect
Detect pipeline, input, UI, packages, tests, folders. Parameters: none.
script_analyze
Analyse one MonoBehaviour, ScriptableObject or user class by class name. Parameters: scriptName, includePrivate?
script_dependency_graph
N-hop dependency closure for one script class name. Parameters: scriptName, maxHops?, includeDetails?
scene_spatial_query
Objects near a point or object. Parameters: x/y/z?, radius?, nearObject?, componentFilter?, maxResults?
scene_materials
Scene materials and shaders. Parameters: includeProperties?
scene_contract_validate
Check default roots, tags, layers and UI EventSystem conventions. Parameters: requiredRootsJson?, requiredTagsJson?, requiredLayersJson?, requireEventSystemForUi?
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/besty0728/unity-skills/unity-perception">View unity-perception on skillZs</a>