Unity Batch Skills

Triggers

• Operating on many objects at once
• Running or polling long async jobs
• Preview-then-commit bulk edits
• 一次性操作大量对象、运行或轮询长时异步任务、先预览后提交的批量编辑

Unity Batch Skills

The POST /skills/batch endpoint, query → preview → execute bulk edits, execution reports and async jobs. Parameters come from the schema, never from a skill's name; execution and dryRun rules: root SKILL.md.

POST /skills/batch — several skills, one HTTP call

An HTTP endpoint, not a skill: never send skills_batch to POST /skill/<name>. It runs up to 50 ordinary skill calls in order inside one main-thread job, each through the full single-skill pipeline (validation, permission gate, its own Undo group, audit): one round trip and one main-thread wake-up instead of N, the biggest saving once there are 3+ writes.

POST /skills/batch
{
  "steps": [
    {"skill": "gameobject_create", "args": {"name": "Cube", "primitiveType": "Cube"}},
    {"skill": "component_add", "args": {"instanceId": {"$ref": "$0.instanceId"}, "componentType": "Rigidbody"}}
  ],
  "continueOnError": false
}

• $ref: an args object whose only key is $ref, {"$ref":"$N.path"}, is replaced by the value at path (e.g. instanceId, results[0].path; bare $N = the whole result) in the result of earlier successful step N (0-based). Only structured args are scanned, never strings. A ref that cannot resolve (forward, failed step, no match) fails its step with SEMANTIC_INVALID. Refer to created objects through $ref (instanceId, or entityId on Unity 6000.4+) rather than by name: a same-named existing object may win a name lookup.
• Query: ?mode=dryRun (the batch dryRun gate) validates every step, executes nothing and never halts; a step may name an object an earlier step would create (a warning notes the skipped live checks) and $ref args get a structural check only (refsValidated). ?mode=transactional is all-or-nothing with Undo rollback, rejected up front (400) for an unknown skill, a step that may trigger a domain reload, or continueOnError:true. ?diff=1 adds a net sceneDiff; ?wire=v2 slims dryRun step payloads; expectInstance / expectProject work as on /skill. ?mode=plan is not supported. mode / dryRun may sit in the body instead: each key resolves query-first and a blank value counts as absent. Any key outside these (body: steps, params, continueOnError, mode, dryRun) is 400 UNKNOWN_PARAM.

Reading the response. HTTP 200 whenever the batch ran; only a rejected request (bad body, >50 steps, unknown mode or key) is 4xx.

{"status":"partial","mode":"execute","dryRun":false,"executed":2,"failed":1,
 "results":[{"index":0,"skill":"...","status":"success","result":{...}},
            {"index":1,"skill":"...","status":"error","error":{"errorCode":"...","error":"..."}},