Unity Skills

Unity Skills

Module and reference docs are English-only. Match requests to modules by meaning in any language, and always reply in the user's language.

Route first: automate, or guide the user?

• Automate — you call REST skills and drive the Editor yourself. Stay here when the user asked you to do it, or the task needs traversal, search, batch, exact numeric values, or consistency across many objects.
• Guide — you name the menus and Inspector fields and write nothing through REST. Switch to SKILL_GUIDE.md (guidance boundary table + manual-* routing) when the user asked how to do it themselves, or /health reports a surfaceProfile other than full.

First Contact Checklist

Before the first skill call in a session:

1. GET /health — discover the server (ports 8090–8100); read currentMode ("approval" / "auto" / "bypass"), panelApprovalRequired, pendingCount, and surfaceProfile (full / guide / noSceneAuthoring). surfaceProfileHint is text only when the profile is not full, else null.
2. Branch on currentMode: under approval the first write to any FullAuto skill returns MODE_RESTRICTED and needs a grant; under auto/bypass writes execute directly (self-assess risk under auto). Grants are single-shot; the permanent form is the user-managed Allowlist. Gates, grant protocol and mode table → operating mode.
3. GET /skills/meta — once per session: the constants shared by every skill (categories, operationTypes, reservedBodyParameters, workflowTrackedSkills, schemaVersion, defaults). Read them here, not out of each manifest, then start discovery.

Schema: pick the cheapest layer

Server-cached (ETag/304), off the main thread; send Accept-Encoding: gzip.

Bare GET /skills is the brief directory — names by category only; the old full listing needs ?full=1.

Module docs and the scoped schema are complements: schema has exact signatures; the module doc has guardrails, return shapes and traps schema omits. On an unfamiliar module read both.

Wire format v2 (?wire=v2)

?wire=v2 slims per-skill entries on ?full=1, /skills/schema (full or scoped), a filtered /skills, and recommend — never bare GET /skills (always the brief directory). v1 is default:

• A flags array replaces v1's six booleans and adds v2-only longRunning: readOnly, tracksWorkflow, mutatesScene, mutatesAssets, mayTriggerReload, mayEnterPlayMode, longRunning. An absent flag is false.
• Omitted means default: riskLevel appears only when not "low", supportsDryRun only when false, null members are dropped — an absent key never reads as null.
• Every v2 response carries a defaults block — take the rule from the payload, don't memorize it.

Execute: batch, dryRun gate, anti-hallucination rules

POST /skills/batch — up to 50 steps per call ({"steps":[{"skill","args"}],"continueOnError":false}; ?mode=dryRun validates every step): the largest round-trip saving available → batch.

Before executing any skill whose exact parameters you don't already hold, dryRun it: POST /skill/<name>?mode=dryRun. Iterate until valid: true, then execute without ?mode=dryRun. valid: true means the four validation error buckets are empty — warnings never block, and target existence is never checked. The top-level authorization ({allowed, blockedBy, currentMode, allowlisted, hint}, plus surfaceProfile on a SURFACE_EXCLUDED block) previews interception: blockedBy is MODE_RESTRICTED, MODE_FORBIDDEN, SURFACE_EXCLUDED, or null when the call would run — settle grants and exclusions there, not on the real call.

After a write, verify in the Editor, not from the echo: *_get_info / *_get_properties, or find_objects_by_name.

Surface profile

surfaceProfile says which slice of the skill surface the user exposed. You cannot change it — the user switches it in the UnitySkills panel. (guideMode is legacy; surfaceProfile is authoritative.)

Calling a hidden skill returns SURFACE_EXCLUDED, and the response names the document to read (or the profile to leave). It is a configuration boundary, not a failure: never retry it, never route around it through another module.

Module routing

Every skill is named module_verb, so the prefix is the routing key. GET /skills/recommend?intent=... ranks candidates, or read the index — all 80 modules with mode labels, incl. docs-only ones (manual-*, *-design, unity-cli) that define no REST skills → module index.

Error codes quick reference

Observability and Unity CLI pointers

Compilation status, events, analytics → observability. Unity CLI cold start (opt-in, v2.3+) → unity-cli.

Current snapshot: 805 REST skills, 56 source files, 54 categories, 82 module documentation directories (54 REST/module docs + 28 advisory docs), Unity 2022.3+, default timeout 15 minutes.

Python helper: unity-skills/scripts/unity_skills.py