/skill-creator

name: skill-creator
description: Guide for authoring user-defined custom UnitySkills skills inside your own Unity project - a [UnitySkill] C# method plus the conventions that let agents and the server discover and gate it

> **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

• Writing your own custom skill for your project
• Extending what agents can do in this specific Unity project
• Learning the [UnitySkill] metadata contract and discovery rules
• 为自己的工程编写自定义技能、扩展 Agent 在本工程可调用的能力

Skill Creator (advisory)

**Audience**: an agent (or developer) adding a **custom skill to your own Unity project**, not to the UnitySkills plugin source. A custom skill is a `public static` method marked `[UnitySkill]` compiled inside your project's Editor code; the server discovers it automatically — you never edit the plugin.

Where the C# must live

Put the file under `Assets/` in an Editor-only location (e.g. `Assets/Editor/UnitySkillsCustom/MySkills.cs`, or any asmdef whose platform is Editor). The plugin's editor asmdef has `autoReferenced: true`, so `Assembly-CSharp-Editor` and ordinary user Editor asmdefs see the public API without adding references.

• **Never** put custom skill code inside the package (`Packages/com.besty.unity-skills/`) or `Library/PackageCache/`: package updates and self-update replace that whole tree and your file is wiped.
• The class need not be a MonoBehaviour; a plain `static class` is fine.

Compile and discovery loop

After you write the C# (through `script_create` with the full `content`, or by any editor), Unity recompiles and performs a domain reload. The router re-runs `TypeCache.GetMethodsWithAttribute<UnitySkillAttribute>()` on the next request, so the new skill is registered automatically — there is no restart, no list to update.

Recommended agent flow: 1. Check the name is free: `GET /skills?q=<prefix>` or read `GET /skills/schema?names=<cand>&wire=v2`. 2. `script_create { scriptName, folder: "Assets/...", content: <full source> }` — returns `{ path, jobId, waitUrl }`. 3. Wait for compile: `GET /jobs/<jobId>?wait=90` (retry through the reload); inspect `resultData.compilation.errors`. `script_get_compile_feedback(scriptPath)` gives on-demand diagnostics. 4. Confirm registration: `GET /skills/schema?names=<your_skill>&wire=v2` should return your skill with its description and parameters. 5. First real call with `?mode=dryRun`.

Note: `script_create` is `MayTriggerReload` + high-risk — it is **NeverInSemi**: it needs Bypass mode or a panel Allowlist entry; ask the user rather than attempting a grant.

Naming rules (read this before choosing a name)

• Skill names are `snake_case` verbs like `gameobject_create`. A user custom skill **must be prefixed** (e.g. `my_`, `acme_`): `my_apply_team_branding`, not `apply_branding`.
• On a name collision the **later-registered** declaration wins, and registration order is not guaranteed — a name that matches a built-in can shadow it (or be shadowed). The registry logs a warning naming both declaring types (`Skill name conflict: '<name>' declared by both <A> and <B>; using the latter.`). Always check the name is free first.
• Provide a matching `xxx_batch` variant when per-item looping makes sense.

The metadata contract (the attribute)

Fill `[UnitySkill]` truthfully — the router, permission gating, schema, and agents all read it:

[UnitySkill("my_greet",
    "First sentence is what the agent reads; mention parameters.",
    Category = SkillCategory.Uncategorized,                 // user skills cannot add enum values
    Operation = SkillOperation.Query,                       // Query | Create | Modify | Delete | Execute | Analyze (combine with |)
    Tags = new[] { "greeting", "demo" },                    // improves /skills/recommend matching
    Outputs = new[] { "message" },                          // MUST be a subset of what you actually return
    TracksWorkflow = false, MutatesScene = false,           // honest risk flags (see below)
    RiskLevel = "low")]                                     // low | medium | high
public static object MyGreet(
    [SkillParam("Who to greet")] string name = "world") { ... }

• **Category**: `SkillCategory` is a closed enum — custom skills cannot add values. Use the nearest existing category or `Uncategorized`. A skill in GameObject/Component/Material/Scene/Sample is hidden under the **Guide** surface profile unless it is a pure read; any writer with `MutatesScene = true` is hidden under **NoSceneAuthoring**. This is intentional: honest metadata, not a loophole to dodge.
• **Risk flags drive permission**: a skill declaring `Operation.Delete`, `MayEnterPlayMode`, `MayTriggerReload`, or `RiskLevel = "high"` is auto-classified **NeverInSemi** — it returns `MODE_FORBIDDEN` under Approval and Auto and only runs in Bypass or via the panel Allowlist. `Mode` defaults to `FullAuto`; declare `Mode = SkillMode.SemiAuto` **only** for a pure read with zero side effects. Fill these truthfully or your skill is gated wrong.
• **Outputs**: every entry must be a key the method actually returns; the schema contract tests check this.

Writing the method body (public API only)

Only the **public** surface is available to project code. Use:

• `Validate.Required(x, "x")` — returns an error object to return early: `if (Validate.Required(x, "x") is object err) return err;`
• `GameObjectFinder.FindOrError(name, instanceId, path)` — never `GameObject.Find`.
• `SkillErrorResponse.Build(SkillErrorCode.X, message, ...)` for business errors (do `throw` only for truly unknown framework errors). `SkillErrorCodeExtensions` is internal — do not try to call it.
• Writers that mutate scene s