nccgs 2.1.1 → 3.0.0-rc.2

package/unity-skills/new-unity-project/SKILL.md

@@ -0,0 +1,386 @@
+---
+name: new-unity-project
+description: Guides creating a new Unity project, gathering concept, platforms, and monetization before setting up the project, source control, and packages. Use when the user asks to start a new game or prototype. Runs an opinionated paved path by default; full interview on request.
+allowed-tools:
+  - Bash
+  - Write
+  - Edit
+---
+
+# New Unity Project
+
+A flow from an idea to a running, version-controlled Unity project. This skill owns the **flow** —
+mode, defaults, ordering, background installs, handoffs.
+
+**Delegates to (read these for the actual commands — don't reinvent them):**
+- **`unity-cli`** — install, auth/license, Editor install, creation, source control, open. Its
+  "Bootstrap a new project from scratch" workflow is the backbone here.
+- **`unity-package-management`** — packages with the Pipeline `package` commands (C# script fallback).
+- **`urp-postprocessing`**, **`ui`**, **`2d-pixel-perfect`** — visual-baseline mechanics (Step 7).
+- **`craft-game-floors`** — the craft floors (look, feel, audio, shell, live floor, the done gate),
+  loaded at Step 6 and carried through the build.
+- **`implement-in-app-purchases`**, **`levelplay-unity-integration`**, **`build-live-game`** —
+  monetization / backend *integration* (invoked at the end).
+
+## Mode: paved by default, guided on request
+
+Run **paved** unless the user asks for the interview — in words ("ask me questions", "guide me")
+or by pushing back on the manifest; mode is decided once per session. The paved contract:
+**parse the prompt first** · **fill gaps from the Defaults table** · **print the manifest** before
+the create launches · **proceed**, asking only on pushback or an unruled fork ·
+**never consume a human gate** — sign-in, license activation and publishing each need the user's
+yes, asked as a question you wait on (see Sign-in and license). A **bare/minimal** ask gets
+`--bare`, skips the floors, and states the cost (identity, saves, ranks unwired). Bare runs Steps
+1–4, installs only the packages the user named in Step 5, skips Steps 6 and 7, then commits (Step 8)
+and hands off monetization (Step 9) without the forward baton.
+
+In **guided** mode, ask only the current step's questions and wait. The paved additions (identity,
+floors, baton) are asked at their steps there, never assumed.
+
+## Sign-in and license (before your first question)
+
+Run `unity auth status --format json` and `unity license status --format json` first. If either
+shows the user signed out or without an active license, ask **one** question that covers both,
+with your client's multiple-choice question tool (plain text only without one), and wait for the
+answer. Send it together with the delegated-skills offer (below) and any Step 1 question, so the
+user answers once. Offer the free
+**Unity Personal** license as the default choice, with the other license types (a subscription the
+account already has, a serial, a floating server) as alternatives. The Personal choice itself says
+that picking it accepts the Unity Personal EULA
+(https://unity.com/legal/editor-terms-of-service/software), so the user sees it before answering.
+
+- Never tell the user to sign in or activate a license themselves, and never hand them commands to
+  run. You run them, after they say yes.
+- On yes, sign in only where the choice needs an account: Personal and an existing subscription
+  activate the signed-in user's licenses, and a cloud-linked project needs one too. Run
+  `unity auth login` then (it opens the browser; the user only completes the sign-in page, so tell
+  them that page is coming), in the background or with its output unfiltered, and pass on the
+  sign-in link it prints in case the browser doesn't open: a pipe through `tail` holds the link
+  back until sign-in ends. Then `unity license activate --personal --accept-eula` for Personal.
+  Serial and floating activation need no account: `unity license activate --floating`, or the
+  serial through `UNITY_LICENSE_SERIAL` and a bare `unity license activate`, so it stays off argv.
+- Declining stops the run before the create only when nothing can license the Editor. A user who
+  declines sign-in but has, or activates, a serial or floating license still gets a local project:
+  create with `--no-cloud` and say the cloud link and player accounts are off.
+
+## The Defaults table
+
+Every row reverses on a word; change a row only with a run-earned receipt.
+
+| Decision | Paved opinion |
+|---|---|
+| Editor version | `--editor-version latest`, explicit |
+| Template | URP; 3D unless the prompt says 2D (`--template 3d` or `2d`) |
+| Platforms | Desktop only; add modules when the prompt implies them ("mobile game" → ios/android) |
+| Monetization | None at creation; noted for later |
+| Version control | Local git + Unity .gitignore |
+| Player identity | Anonymous accounts — create's when its result shows them, else wired in Step 6 |
+| Craft floors | Always on, via the `craft-game-floors` skill: look, camera, lighting, feedback, audio, shell, live floor, done gate |
+
+Cloud link and diagnostics are **not** a row: create applies its own defaults — narrate them from
+the result, don't re-decide.
+
+## The assumptions manifest
+
+Print exactly one block at the end of Step 2, before the create launches. It **predicts** what
+create will do (the URP template per `--template 3d|2d`, never a guessed id):
+
+> **Paved assumptions:** Unity <editor> · <URP template, 2D/3D> · <platforms> · <monetization> ·
+> anonymous player accounts (create's, else one bootstrap script) · <version control> ·
+> cloud-linked with diagnostics (create's defaults, narrated from the result) · floor packages
+> (Cinemachine; identity + live services when cloud-linked) · craft floors on via `craft-game-floors` ·
+> a one-line handoff note for the project's CLAUDE.md, written only on your yes.
+> Say the word to change any of these; otherwise I'm proceeding.
+
+One block, every assumption present, each reversible, nothing implied; Step 3 reconciles the
+result against it.
+
+## Before Step 1: check the delegated skills are loaded
+
+Look for `unity-cli`, `unity-package-management`, `urp-postprocessing`, `ui`, `build-live-game`
+and `craft-game-floors` in your client's skills. If any is missing, say which and what it does, and offer the install routes
+in [references/skill-setup.md](references/skill-setup.md), in the same question as sign-in and
+license when that one goes out — never install without a yes. Don't
+stall: a decline gets the fallback at its step, gap named in the report. `unity skill show` prints
+`unity-cli` without installing; without `unity-package-management`, Step 5 can't run — say so
+before Step 2.
+
+## The flow — and where the parallelism is
+
+1. **Concept** (paved: parsed from the prompt). 2. **Platforms & monetization** — print the
+manifest (paved), then **start the create in the background**: `projects create --install-editor`
+installs the Editor + modules (minutes), then creates the project; keep talking meanwhile.
+3. **(joins)** reconcile the result against the manifest. 4. **Source control.** 5. **Packages.**
+6. **Player identity, then the craft floors** — confirm create's identity or wire it; load
+`craft-game-floors`. 7. **Visual baseline** on the craft skill's art bible. 8. **Save & first commit.**
+9. **Hand off** + the forward baton.
+
+The multi-minute Editor install overlaps the user's answers, so setup feels instant.
+
+## Step 1 — Concept
+
+**Paved:** the prompt is the spec — parse genre, dimension (2D/3D), look, scope, and name into a
+2–4 line brief; fill gaps from the Defaults table; no read-back.
+
+**Guided:** ask with your client's multiple-choice tool (`AskUserQuestion` in Claude Code,
+`ask_user` in Copilot CLI, `askQuestions` in VS Code); without one, plain text.
+Cover **genre / core loop** · **dimension & look** (2D or 3D; pixel, low-poly, stylized,
+realistic) · **gameplay** (the one-sentence "what the player does moment to moment") · **scope**
+(prototype vs. multi-scene; single- or multiplayer). Settle a **project name**, write the brief,
+read it back. The brief drives the template (Step 2), packages (Step 5) and the baseline (Step 7):
+note the palette / mood words and pixel-art looks.
+
+## Step 2 — Platforms & monetization, then start installing
+
+Two decisions (paved: filled from the Defaults table, then **print the manifest**):
+
+- **Target platforms**: Desktop, Mobile (iOS/Android), WebGL, Console — they map to Editor
+  **modules** (`--module`) and argue for leaner packages on mobile/WebGL.
+- **Monetization**: none / premium / IAP / ads / mix — this only decides the Step 9 handoff.
+
+Default to an explicit `--editor-version latest` unless the user names a version — without the
+flag, create prefers a stored default or an older installed Editor.
+
+Confirm prerequisites, then **start the create as a background task** (`unity-cli` has module
+names and auth / license setup):
+
+```bash
+unity --version   # sign-in and license: settled before your first question (see above)
+
+# Start in the BACKGROUND. Module names per platform are in the unity-cli skill.
+# --bare only on the user's ask (see Mode).
+unity projects create "<Name>" --path <dir> --editor-version latest \
+  --template <3d|2d> --install-editor --module <platform-modules> --accept-eula --format json
+```
+
+The command waits for the install, then creates the project, so its one result covers both. If you
+have nothing left to ask, it's fine to just wait.
+
+**Template:** `--template 3d` / `2d` resolve to the version's URP templates
+(`com.unity.template.urp-blank`, `com.unity.template.universal-2d`), the default for every game.
+Built-in templates (`com.unity.template.3d`/`.2d` as full ids) are deprecated from 6.5, removed in
+6.7 — pass one only when the user explicitly asks for Built-in.
+
+## Step 3 — Join: project ready, result reconciled
+
+Wait for the background create and read its JSON result: `data.path` is the project,
+`data.version` the Editor, `data.editorInstalled` whether this run installed it.
+
+**Paved: reconcile the result against the manifest**, narrating divergence — the cloud-link
+soft-fail included (`cloudLinked: false`, warnings, project intact; Step 6 keys off it). A 403 on
+the link is often the saved default org refusing new projects — retry
+`unity projects link cloud <path> --cloud-org <an org the user owns>` before concluding
+no-identity. A result carrying a `steps` field reconciles step-by-step from it.
+
+`--module` only applies when the run installs the Editor: on `data.editorInstalled: false`, add
+the platform modules with `unity install-modules -e <version> -m <platform-modules> --accept-eula`
+(skips what's already there). If create failed, surface the error (`unity-cli` troubleshooting)
+and stop — a failed install creates no project, and nothing downstream works without an Editor.
+
+## Step 4 — Source control
+
+**Paved:** local git + Unity `.gitignore`. **Guided:** ask — Git (GitHub / GitLab; `--git-lfs` for
+asset-heavy games), **Unity Version Control** (`--vcs uvcs` — large binaries natively, no LFS), or
+purely local. Attach with `unity projects link vcs "<project-path>" --vcs …
+--git-token-from-stdin --no-initial-commit` (tokens on stdin) — **`--no-initial-commit`** keeps
+the CLI from committing the bare project before packages and `.meta` files exist; the real first
+commit is Step 8. Exact flags: the `unity-cli` workflow.
+
+## Step 5 — Packages
+
+Map the brief to a package list and install via **`unity-package-management`** (**never**
+hand-edit `manifest.json`): `package add` once the Editor is open with `com.unity.pipeline`
+(Step 7); its C# installer script when packages must land pre-open (the `-quit` gotcha applies).
+That skill has the genre/platform/monetization → package mapping. A `--bare` run installs only the
+packages the user named, through the C# installer script (bare has no `com.unity.pipeline`, so
+`package add` can't run; never `unity pipeline install` to get it, which undoes the bare ask), and
+stops there. Otherwise paved
+adds the floors' needs: Cinemachine for any gameplay camera (2D rigs included);
+`com.unity.services.authentication` when Step 6 wires identity; and the live floor's services set
+on cloud-linked projects — in this pass, not at shell time. Cloud save and remote config come from
+create: when its `steps` report `cloudSave` and `remoteConfig` as `done` or `present`, skip them and
+add only what is left (leaderboards). The template already provides the
+render pipeline — never add `com.unity.render-pipelines.universal` on a Built-in template
+(materials go pink) or vice versa. Read the list back before installing (paved: print it now);
+verify `manifest.json` after.
+
+## Step 6 — Player identity, then the craft floors
+
+**Identity — the create result is the switch** (a `--bare` run skips this whole step: bare
+projects still cloud-link unless `--no-cloud`, and the unwired cost was stated at Mode time):
+identity addressed in the result → confirm it in the reconciliation and **skip**, never wire auth
+twice. No identity and the project cloud-linked →
+wire it: services init plus anonymous sign-in kicked off at bootstrap in **one small bootstrap
+script**, never blocked on (mechanics: **`build-live-game`**, auth section — checked in Before
+Step 1; missing and declined → skip the wiring, gap named); each service dependency is a named
+plan line, declining removes only that line. Cloud link failed or skipped →
+skip with the cost stated (saves and ranks stay local) — never wire services init against a
+project with no cloud id. Invisible to players, upgradeable later — the root the live floor
+builds on.
+
+**A `--bare` run skips the floors too** (the Mode section's stated cost). Otherwise **load the
+`craft-game-floors` skill** (checked in Before Step 1) and follow its floors through the
+build — art bible first, then camera, lighting, feedback, audio, shell, live floor, its done gate.
+Its values supersede the inline fallbacks below whenever present, version skew included. Missing
+and declined → fallbacks, gap named in the report.
+
+## Step 7 — Visual baseline
+
+A fresh template renders correctly but looks like a default; left there, agents reach for `OnGUI`
+and guess shader names. Apply this floor **before** any gameplay work. A `--bare` run skips this
+whole step (no Pipeline install, no baseline): go to Step 8, which opens the project.
+
+**On Unity 6000.5.0 to 6000.5.2, stop here.** The Pipeline package can't start its server on those
+Editors (create reports `PIPELINE_EDITOR_UNSUPPORTED`), so nothing below can connect, and reopening
+won't help. Create also left the package out on those Editors. Ask the user to update to
+6000.5.3f1 or later, then continue below with the project still closed: the Pipeline install comes
+first, then the open names the updated Editor, `unity open "<project-path>" --editor-version
+<updated-version>` — a plain `unity open` reopens with the project's saved 6000.5.x Editor. If the
+update is 6000.7 or later, `unity open` refuses that move (`PROJECT_UPGRADE_REQUIRED`): run
+`unity projects upgrade "<project-path>" --to <updated-version> --yes` instead. It asks
+nothing: add `--no-cloud` when the user declined the cloud link at create, since an unlinked
+project otherwise exits `CLOUD_CHOICE_REQUIRED`, and no cloud flag when create linked it.
+
+**First, `unity pipeline install --project-path "<project-path>"`, before opening the
+Editor.** Running C# in the Editor and `unity command capture screenshot` below both need the
+project's `com.unity.pipeline` package. Create adds it by default on newer CLIs (this install then
+changes nothing); older CLIs leave the project without it, and Step 5's `-batchmode` installer
+never touches it. Install-before-open is the supported order; without the package, everything below fails to
+connect (it mimics `unity-cli`'s Safe Mode failure). The failure codes
+(`PIPELINE_MANIFEST_WRITE_FAILED`, a stuck `STATUS_PIPELINE_LOAD_PENDING`) and the stuck-Editor
+recovery are tabled in [references/skill-setup.md](references/skill-setup.md).
+
+**Then** `unity open "<project-path>"`, wait until `unity status` reports the Editor ready, and
+apply each item below by running C# in it — **`unity-cli` owns those commands**; don't re-derive
+them here.
+
+Once the Editor is ready, read the `unity-pipeline` guide if your skills don't list it —
+locations and mirroring routes: [references/skill-setup.md](references/skill-setup.md).
+
+**Items 1, 2, 5 and 6 assume a URP template**, the Step 2 default. If the user explicitly chose
+Built-in, don't run them as written — `UniversalAdditionalCameraData`, `Light2D`, the
+`urp-postprocessing` volume framework and `Universal Render Pipeline/*` shaders don't exist there;
+post-processing means the legacy Post Processing Stack, the shader names are `Standard` /
+`Unlit/Color`, and items 3–4 apply as written. Don't reach for `migrate-birp-to-urp` — the user
+asked for Built-in.
+
+1. **Post-processing.** Global Volume — `craft-game-floors`'s scene-lighting values when loaded (they
+   supersede these); fallback: Tonemapping (ACES), Bloom intensity 0.5–1 @ threshold 0.9, Vignette
+   ≈ 0.25; set `renderPostProcessing = true` on the main camera's `UniversalAdditionalCameraData`.
+   **REQUIRED SUB-SKILL:** `urp-postprocessing` — its templates create the volume and check HDR and
+   the layer mask; if it isn't loaded, do both yourself from these values.
+2. **Camera and light.** 2D → orthographic, solid background from the brief's palette, a `Light2D`
+   of type Global if the template scene has none (Sprite-Lit shaders render black without one).
+   3D → perspective, main-light shadows on; `craft-game-floors`'s lighting pass replaces the template's
+   default light story when loaded, else keep the template's directional light and skybox.
+3. **Quality tier.** Read `QualitySettings.names` first — tier names differ per template — then
+   `QualitySettings.SetQualityLevel` to the one matching the primary target: the highest tier for
+   desktop, the lowest for mobile/WebGL. Leave color space Linear and the Input System as the
+   template set them.
+4. **UI stack.** HUD and menus use a uGUI Canvas + TextMeshPro or UI Toolkit — **never `OnGUI`**.
+   **REQUIRED SUB-SKILL:** `ui` picks between them for the project. If it isn't loaded, choose
+   between them from the brief and say which you chose, and why, in your final report.
+5. **Materials and shaders.** Under URP use `Universal Render Pipeline/Lit`, `…/Unlit`,
+   `…/2D/Sprite-Lit-Default` or `…/2D/Sprite-Unlit-Default`. `Standard` and `Unlit/Color` render
+   pink or washed out under URP. Prefer `GraphicsSettings.currentRenderPipeline.defaultMaterial`
+   / `.default2DMaterial` over `Shader.Find`, and treat a `null` from `Shader.Find` as an error.
+   `currentRenderPipeline`, not `defaultRenderPipeline`: a quality tier can carry its own pipeline
+   asset, and item 3 above just set the tier.
+6. **Pixel art only.** Point filter mode on sprites and a Pixel Perfect Camera — see
+   `2d-pixel-perfect`. If missing, do both yourself and note the skill-setup install route in the
+   report.
+
+Save the scene, then confirm both of these — **not with `unity logs`**, which reads the CLI's own
+log and reports clean whatever the scene looks like:
+
+- No render-pipeline or shader errors Editor-side. Read the Editor console through `unity-cli`,
+  or read `Editor.log` directly — that skill's "Recovering from Safe Mode" section has the
+  per-platform paths.
+- `unity command capture screenshot --output baseline.png` looks lit and tonemapped rather than flat
+  gray.
+
+## Step 8 — Save & first commit
+
+The project is already open from Step 7, so `.meta` files exist (`unity open "<project-path>"`
+only if not — headless/CI uses the "Import & save headlessly" method in
+`unity-package-management`). Commit **with whichever VCS you set up in Step 4**:
+
+- **Git (GitHub / GitLab / local):**
+  ```bash
+  cd "<project-path>"
+  git add -A
+  git status                    # Library/ Temp/ obj/ Build/ must NOT be staged
+  git commit -m "Initial Unity project: <Name>"
+  ```
+  Every `.cs`/asset is committed together with its `.meta`.
+- **Unity Version Control (UVCS):** check in through the workspace from Step 4 — no `git` step;
+  generated folders stay excluded by the ignore rules.
+
+If Step 7 mirrored skills into the project, ask whether to include them. If Step 4 linked
+**without** `--no-initial-commit`, the CLI already committed the bare project — add a follow-up
+commit rather than double-committing.
+
+## Step 9 — Hand off
+
+Based on Step 2 monetization, invoke the matching skill for the actual integration:
+- IAP → **implement-in-app-purchases**
+- Ads → **levelplay-unity-integration**
+- Accounts / cloud save / economy / remote config / leaderboards → **build-live-game**
+
+If the matching skill isn't loaded, point the next steps at the skill-setup install route rather
+than integrating from memory.
+
+**Offer the forward baton** (declared on the manifest; not on a `--bare` run): one idempotent line
+for the project's `CLAUDE.md` or `AGENTS.md` — "When building gameplay, feel, audio, shell, or live
+features, load the `craft-game-floors` skill; if it isn't installed, ask the user whether to run
+`unity skill install <client>` (ask: never run it without a yes)." That file steers every later
+agent session in the project, so **ask before writing it**, even in paved mode, and show the line.
+On a yes, append it and commit the note — appended after Step 8, it otherwise never reaches clones.
+On a no, put the line in the report for the user to add. Later sessions reach the floors through
+it without this skill re-triggering.
+
+Report the project path, Editor version, pipeline and template, packages, the manifest with its
+reconciliation, identity state, the baseline applied, any missing skill, `craft-game-floors`'s done gate
+as the build's finish line, and next steps.
+
+## Scope — what this skill does NOT do
+
+- **No gameplay scaffolding.** A running, wired project with a visual floor; the game is the next
+  conversation (with `craft-game-floors`). One exception: Step 6's single bootstrap script.
+- **No command reference.** Syntax lives in `unity-cli` / `unity-package-management`.
+- **No re-deciding create's defaults** — narrate them from the result. The Defaults table is this
+  file's only opinions; the guided interview survives untouched.
+
+## Checklist
+
+- [ ] Delegated skills checked before Step 1 (incl. `craft-game-floors`): a missing one offered, or named
+      in the report
+- [ ] Mode decided once; in paved, the manifest printed before the create launches
+- [ ] Brief captured; platforms + monetization recorded
+- [ ] Background create with `--install-editor` + modules, URP template (`--template 3d`/`2d`)
+      unless Built-in was requested; `--bare` only on the user's ask; result reconciled
+- [ ] Source control attached (Step 4), or local git + Unity `.gitignore`
+- [ ] Packages via `package add` (or the C# script pre-open); `manifest.json` verified; no
+      render-pipeline package atop the template
+- [ ] Identity confirmed from the result or wired in Step 6 (stated cost on a failed link)
+- [ ] `craft-game-floors` loaded (or its absence named); `unity-pipeline` read once the Editor was ready
+- [ ] Baseline applied: Volume + camera post on, quality tier, UI stack (no `OnGUI`), URP shaders,
+      capture checked (skipped on `--bare`; on 6000.5.0–6000.5.2, Editor updated first)
+- [ ] `.meta` files exist; first commit made; `Library/` excluded
+- [ ] Forward baton offered and written only on a yes (none on `--bare`); handoff done if applicable
+
+## Common mistakes
+
+- **Blocking on the create** instead of backgrounding it: with `--install-editor` it waits for the
+  whole Editor install.
+- **Acting before the manifest prints** (paved), or burying an assumption outside it — if it isn't
+  in the manifest, it isn't assumed.
+- **Wiring auth twice** — if create's result shows identity, Step 6's wiring is a skip.
+- **Hand-editing `manifest.json`** instead of the package commands or the skill's script.
+- **Doing a required sub-skill's job from memory** when it isn't loaded, without telling the user
+  or offering the install.
+- **Committing `Library/`/`Temp/`/`obj/`/`Build/`**, or scripts without their `.meta` files.
+- **Missing Editor modules** — a mobile target needs `android`/`ios`; WebGL needs `webgl`.
+- **Picking `com.unity.template.2d` / `.3d` by name** — Built-in templates; use `--template 3d`/`2d`.
+- **Skipping the visual baseline** — flat template defaults, `OnGUI` HUDs, and
+  `Shader.Find("Standard")` under URP.

package/unity-skills/new-unity-project/references/skill-setup.md

@@ -0,0 +1,66 @@
+# Skill setup — getting the delegated skills loaded
+
+> Reference for the `new-unity-project` skill: the install routes for its delegated skills, and the
+> `unity-pipeline` guide's location inside the Pipeline package. The body's "Before Step 1" check says
+> *when* to use this; this file says *how*.
+
+## Install routes, by client
+
+If a delegated skill is missing, tell the user which one and what it does for them. Offer to install
+the Unity skills before you start, and don't install without a yes, because it changes their agent
+setup:
+
+- **Claude Code, with none of the Unity skills installed:** `unity setup claude --format json`
+  installs the Unity plugin, which carries all of them. It would duplicate any you already have. An
+  older CLI doesn't know `unity setup`, so use the next route then. A fresh install loads in the next
+  session, or after `/reload-plugins`. Until then, read the skills from the `skillsPath` it reports.
+- **Any other case, including a partial set:** run `unity skill install <client>`, where
+  `unity skill install --list` names the clients and where each one installs. It installs the Unity
+  skills from the Unity-Technologies/skills repository at the commit this CLI pins, and checks each
+  one against that pin before it writes anything. To add only the missing skills, name each with
+  `--skill`, which repeats and takes a comma list (`--skill ui,localization`). The source is fixed in
+  the CLI, so don't look for a flag to point it elsewhere. Offline, it installs only the two skills
+  built into the CLI (`unity-cli` and `new-unity-project`), names the ones it couldn't install, and
+  exits 0: run it again once the machine is online.
+- **Codex, Grok Build or GitHub Copilot CLI whose plugin can't be installed:** `unity setup <agent>`
+  offers the same repo skills instead when the agent's CLI is missing or its plugin install fails.
+  With the user's yes, `unity setup <agent> --yes --format json` installs them without a prompt and
+  reports `installedVia: "skills"`, the `skillsPath` and the `skillsToLoad` it installed. The same
+  works for `unity setup claude`.
+- **An older CLI** installs only `unity-cli` and `new-unity-project`. There, tell the user to copy
+  each missing skill's folder from github.com/Unity-Technologies/skills (under `skills`) into their
+  client's skills folder.
+
+A newly installed skill may not load until the client restarts. If it still isn't listed, ask where
+the installer put it and read the skill file from there.
+
+## The `unity-pipeline` guide (read it once the Editor is ready)
+
+It is the Pipeline package's own guide, and no client loads it from the package folder. If it is
+missing from your skills, read its skill file directly. It sits under
+`.claude/skills/unity-pipeline/` in the package: `Packages/com.unity.pipeline/` if the project embeds
+the package, otherwise the `Library/PackageCache/com.unity.pipeline@*` folder. List
+`Library/PackageCache` for the exact name, since the suffix is often a hash, not the version.
+
+To have your client load it in later sessions, `unity skill install <client> --local` can mirror it,
+but only for a client with a project scope (`unity skill install --list` shows which, and Claude
+Desktop has none). It also writes a project copy of `unity-cli` beside it. The `unity-cli` skill
+suggests running it once, but here, wait until the user asks, and run it from the project folder
+after the open. In Claude Code with the Unity plugin installed it stops short, because the plugin
+already carries `unity-cli`. There, with the user's yes, copy the `unity-pipeline` folder into the
+project's `.claude/skills/` instead. Where no mirror is possible, read the package copy again in each
+session.
+
+## Pipeline failure codes and the stuck-Editor recovery
+
+| Symptom | Cause | Resolution |
+|---|---|---|
+| `PIPELINE_MANIFEST_WRITE_FAILED` on `unity pipeline install` | the project is open in an Editor | ask the user to close the Editor, re-run the install |
+| `STATUS_PIPELINE_LOAD_PENDING` right after an install against an open project | the open Editor loads the package when its window regains focus | ask the user to switch to the Editor window |
+| `STATUS_PIPELINE_LOAD_PENDING` that never clears after an open | the Pipeline server can run while its port file never lands (package/editor pairing issues) — focus is not the cause | read `Logs/Editor.log` for `Pipeline:` lines to confirm, then recover below |
+| Pipeline never connects on Unity 6000.5.0 to 6000.5.2 (create reported `PIPELINE_EDITOR_UNSUPPORTED`) | the package can't start its server on those Editors | don't recover below, reopening won't help: ask the user to update to 6000.5.3f1 or later, run `unity pipeline install` with the project closed (create left the package out), then open it with `unity open "<project-path>" --editor-version <updated-version>` (a plain `unity open` uses the saved 6000.5.x Editor); on 6000.7 or later `unity open` refuses the move, so run `unity projects upgrade "<project-path>" --to <updated-version> --yes`, adding `--no-cloud` when the user declined the cloud link at create |
+
+**Stuck-Editor recovery** (check the project's Editor version first; never on 6000.5.0 to
+6000.5.2, see the table): ask the user first — unsaved work is lost — then
+`unity close <project> --force`, which terminates by PID and works without Pipeline connectivity,
+and reopen the project.

package/unity-skills/optimize-audio/SECURITY.md

@@ -0,0 +1,16 @@
+# Security notes: optimize-audio
+
+This skill has the agent run C# inside the user's open Unity Editor through `unity command script eval`. Automated skill scanners flag that as a powerful capability. It is intentional, and it is limited by the safeguards below.
+
+## Accepted risks
+
+| Risk | Capability | Why it is accepted |
+|---|---|---|
+| `SEC_POWER_CAP` | Runs C# in the user's open Editor through `unity command script eval` | It only reaches the Editor the user already has open, on their own machine, as that user, so it grants nothing they couldn't do themselves. `script eval` sits behind the Pipeline capability gate. No code fetched from a remote source is run. Where a named `unity command` covers a step, the skill uses that instead of `script eval`. |
+
+## Mitigations
+
+- **Only the user's own Editor.** `unity command script eval` talks to the Editor open on this machine. It can't reach another machine or another user's Editor.
+- **Capability gate.** `script eval` is only available when the project's Pipeline package provides it.
+- **No remote code.** The agent runs C# it writes from this skill's own recipes. Nothing downloaded from outside is executed.
+- **Named commands first.** When a dedicated `unity command` covers a step, the skill uses it instead of `script eval`.

package/{.claude/skills → unity-skills}/optimize-audio/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: optimize-audio
-description: Optimizes Unity 6 audio memory, CPU cost, and playback quality through correct import settings and mixer configuration. Use when the user wants to reduce audio memory usage, choose the right Load Type for short clips versus music versus ambient beds, configure platform-appropriate sample rates and codecs, force 3D audio to mono, or reduce AudioMixer CPU cost from deep group trees or effects running on silent paths.
+description: Optimizes audio memory, CPU cost, and playback quality through import settings and mixer configuration. Use when asked to reduce audio memory or Audio Mixer CPU cost, change clip Load Types, sample rates or codecs, or force 3D audio to mono.
 ---
 ## Critical Rules
 
@@ -19,20 +19,20 @@ and discovering the Editor's command catalog. Follow it first; don't re-derive a
 
 Two things it can't know for you:
 
-- **You need `eval` in particular**, not just a reachable Editor. Confirm it appears in the
+- **You need `script eval` in particular**, not just a reachable Editor. Confirm it appears in the
   catalog. Its presence depends on the Pipeline package version, not on the CLI, so a healthy
   install can still lack it — if it's missing, say so and stop.
 - **Do not hand-edit `.meta` files to change import settings.** Importer values only take effect
   through `SaveAndReimport()` in a live Editor, so an unreachable Editor is a stop, not a cue to
   edit metadata directly.
 
-Run C# with `unity command eval --code '<snippet>'`. Discover the parameter shape from
+Run C# with `unity command script eval --code '<snippet>'`. Discover the parameter shape from
 `unity command --format json` rather than assuming one. `unity command` defaults to a 30 second
 timeout.
 
-### Passing C# to `eval`
+### Passing C# to `script eval`
 
-`eval` compiles a **statement block, not a file**. Two consequences, both of which cause a compile
+`script eval` compiles a **statement block, not a file**. Two consequences, both of which cause a compile
 error rather than a warning:
 
 - **No `using` directives.** The compiler reads `using UnityEngine;` as a resource-disposal
@@ -41,13 +41,13 @@ error rather than a warning:
   (`CS0246` / `CS0103`), and a bare `Object` is ambiguous with `object` (`CS0104`).
 
 The recipes in [resources/audio-import-api.md](resources/audio-import-api.md) are written
-fully qualified so they can be passed to `eval` as-is.
+fully qualified so they can be passed to `script eval` as-is.
 
 ## 1. Pre-Flight: Detect Audio System
 
 Before doing anything else, establish the audio environment:
 
-1. **Detect platform and sample rate:** Use `eval` to read `EditorUserBuildSettings.activeBuildTarget` and `AudioSettings.outputSampleRate`. The output sample rate affects whether overriding clip sample rates will actually save memory.
+1. **Detect platform and sample rate:** Use `script eval` to read `EditorUserBuildSettings.activeBuildTarget` and `AudioSettings.outputSampleRate`. The output sample rate affects whether overriding clip sample rates will actually save memory.
 2. **Detect AudioMixer presence:** Use the mixer-asset query recipe in [resources/audio-import-api.md](resources/audio-import-api.md) to see if a mixer graph exists. If none exists, note that routing and effect costs are not a concern.
 3. **Detect AudioListener:** Use the scene-component query recipe in [resources/audio-import-api.md](resources/audio-import-api.md) for `UnityEngine.AudioListener` to confirm exactly one listener is present. Multiple listeners produce incorrect spatialization; zero listeners produce silence.
 4. **Proceed** only after platform and listener state are confirmed.
@@ -56,8 +56,8 @@ Before doing anything else, establish the audio environment:
 
 Before recommending any change, gather observable data:
 
-1. **Find all AudioSources:** Use the scene-component query recipe in [resources/audio-import-api.md](resources/audio-import-api.md) for `UnityEngine.AudioSource`. For each result, use **one** `eval` call to batch-read properties — see the batch read recipe in [resources/audio-import-api.md](resources/audio-import-api.md).
-2. **Inspect mixer topology:** If a mixer was found in Pre-Flight, use `eval` to read the AudioMixer's exposed parameters and group count. A group count above ~8 or effects on the Master group are immediate flags.
+1. **Find all AudioSources:** Use the scene-component query recipe in [resources/audio-import-api.md](resources/audio-import-api.md) for `UnityEngine.AudioSource`. For each result, use **one** `script eval` call to batch-read properties — see the batch read recipe in [resources/audio-import-api.md](resources/audio-import-api.md).
+2. **Inspect mixer topology:** If a mixer was found in Pre-Flight, use `script eval` to read the AudioMixer's exposed parameters and group count. A group count above ~8 or effects on the Master group are immediate flags.
 3. **Check DSP buffer size:** Use the DSP buffer recipe in [resources/audio-import-api.md](resources/audio-import-api.md) to read buffer size. See DSP Buffer Size Guidelines in [resources/platform-settings.md](resources/platform-settings.md) for recommended values.
 4. **Report findings before making changes:** Summarize ALL detected sources, the listener count, and mixer depth to the user. Flag any immediate risks (e.g., stereo clip with `spatialBlend = 1`, Decompress On Load on a clip > 1 MB, reverb on the Master group).
 
@@ -88,15 +88,15 @@ Use the findings from Section 2 to determine which sub-section applies. More tha
 
 For any AudioSource where `spatialBlend > 0` (3D positioned sound):
 
-1. **Check clip channel count:** Use `eval` to read `audioSource.clip.channels`. If `channels == 2` and `spatialBlend == 1`, only the left channel plays — this is a bug, not a feature.
+1. **Check clip channel count:** Use `script eval` to read `audioSource.clip.channels`. If `channels == 2` and `spatialBlend == 1`, only the left channel plays — this is a bug, not a feature.
 2. **Recommend Force To Mono:** Use the read importer recipe in [resources/audio-import-api.md](resources/audio-import-api.md) to inspect current settings, then apply Force To Mono using the force-to-mono recipe.
 3. **Apply and reimport:** Report before/after channel counts to the user.
-4. **Verify spatial blend:** Use `eval` to confirm `audioSource.spatialBlend` is `1.0` (full 3D) and `audioSource.rolloffMode` is set to an appropriate curve.
+4. **Verify spatial blend:** Use `script eval` to confirm `audioSource.spatialBlend` is `1.0` (full 3D) and `audioSource.rolloffMode` is set to an appropriate curve.
 
 ### 4B. AudioMixer Audit
 
-1. **Measure group depth:** Use `eval` to walk the mixer's group tree and count levels. More than 3 levels (Master → SFX / Music / Voice → sub-bus) adds routing overhead every frame, even when children are silent.
-2. **Check effects on silent groups:** Use `eval` to query each group's effects list. Effects such as `AudioReverbFilter` run their DSP at full cost even when no AudioSource routes to that group.
+1. **Measure group depth:** Use `script eval` to walk the mixer's group tree and count levels. More than 3 levels (Master → SFX / Music / Voice → sub-bus) adds routing overhead every frame, even when children are silent.
+2. **Check effects on silent groups:** Use `script eval` to query each group's effects list. Effects such as `AudioReverbFilter` run their DSP at full cost even when no AudioSource routes to that group.
 3. **Flag SFX Reverb on parent groups:** This is the most expensive built-in effect. If found on the Master or a high-level group, flag it explicitly.
 4. **Present recommendations to the user:**
    - Remove or bypass effects on groups that have no active sources.
@@ -122,7 +122,7 @@ For any AudioSource where `spatialBlend > 0` (3D positioned sound):
 
 ### 4E. Load Type and Streaming
 
-1. **Audit Load Type per clip:** Use `eval` to read `clip.loadType` for each clip found in Section 2.
+1. **Audit Load Type per clip:** Use `script eval` to read `clip.loadType` for each clip found in Section 2.
 2. **Apply the decision rule:** See Load Type Decision Table in [resources/platform-settings.md](resources/platform-settings.md).
 3. **Flag mismatches:** See Load Type Mismatch Flags in [resources/platform-settings.md](resources/platform-settings.md). Report both types of mismatches to the user.
 4. **Apply `Load In Background`** for any Streaming clip — use the Load In Background recipe in [resources/audio-import-api.md](resources/audio-import-api.md).
@@ -131,7 +131,7 @@ For any AudioSource where `spatialBlend > 0` (3D positioned sound):
 
 After any import setting or mixer change:
 
-1. **Re-read clip stats:** Use `eval` to re-read `clip.loadType`, `clip.channels`, `AudioSettings.outputSampleRate`, and the importer's `compressionFormat` to confirm the change applied after reimport.
+1. **Re-read clip stats:** Use `script eval` to re-read `clip.loadType`, `clip.channels`, `AudioSettings.outputSampleRate`, and the importer's `compressionFormat` to confirm the change applied after reimport.
 2. **Confirm AudioSource routing:** Use the scene-component query recipe for `UnityEngine.AudioSource` and verify `audioSource.outputAudioMixerGroup` is assigned as expected after any mixer restructure.
 3. **Report delta:** State the before and after values for each setting changed. Do not assume the change was effective without reading back the applied importer values.
 4. **Iterate limit:** Maximum 3 adjust-and-verify cycles before pausing to ask the user for feedback.
@@ -154,7 +154,7 @@ After any import setting or mixer change:
 ### AudioMixer CPU spike — DSP thread hot
 
 1. Confirm with the mixer-asset query recipe that the mixer graph exists.
-2. Use `eval` to list all groups and their attached effects. Look for reverb, chorus, or EQ on high-level groups.
+2. Use `script eval` to list all groups and their attached effects. Look for reverb, chorus, or EQ on high-level groups.
 3. Move expensive effects down to leaf groups that are only active when sources are playing.
 4. Use snapshots to bypass effect chains during gameplay states where they are not heard (e.g., bypass reverb during a menu).
 5. If the DSP buffer is small (64 or 128 samples), raise it — see DSP Buffer Size Guidelines in [resources/platform-settings.md](resources/platform-settings.md).
@@ -168,7 +168,7 @@ After any import setting or mixer change:
 
 ### AudioListener count is not exactly one
 
-- **Zero listeners:** All audio will be silent. Use `eval` to add an `AudioListener` component to the main camera: `UnityEngine.Camera.main.gameObject.AddComponent<UnityEngine.AudioListener>()`.
+- **Zero listeners:** All audio will be silent. Use `script eval` to add an `AudioListener` component to the main camera: `UnityEngine.Camera.main.gameObject.AddComponent<UnityEngine.AudioListener>()`.
 - **Multiple listeners:** Unity uses the last enabled one, producing unpredictable spatialization. Use the scene-component query recipe for `UnityEngine.AudioListener` and disable all but the intended one.
 
 ### `Load In Background` causes first-play silence

package/{.claude/skills → unity-skills}/optimize-audio/resources/audio-import-api.md

@@ -1,9 +1,9 @@
 # Audio Import API Recipes
 
-C# code recipes for `unity command eval --code '<snippet>'`. All examples target the Unity 6
+C# code recipes for `unity command script eval --code '<snippet>'`. All examples target the Unity 6
 AudioImporter API.
 
-`eval` compiles a statement block, so there are no `using` directives and every type is written
+`script eval` compiles a statement block, so there are no `using` directives and every type is written
 fully qualified. Each recipe `return`s its result as a string rather than calling `Debug.Log`, so
 the value comes back on the CLI's stdout instead of only reaching the Editor console.
 
@@ -75,7 +75,7 @@ importer.SaveAndReimport();
 
 ## Read AudioSource Properties (Batch)
 
-Read multiple properties in a single `eval` call:
+Read multiple properties in a single `script eval` call:
 
 ```csharp
 var src = audioSource;
@@ -103,7 +103,7 @@ if (path.EndsWith(".mp3", System.StringComparison.OrdinalIgnoreCase))
 
 ## Resolving `audioSource` / `clip` inside a snippet
 
-The recipes above are written against an `audioSource` or `clip` variable. `eval` runs each
+The recipes above are written against an `audioSource` or `clip` variable. `script eval` runs each
 snippet in a fresh scope, so nothing carries over between calls — resolve the object at the top of
 the same snippet that uses it.
 
@@ -140,7 +140,10 @@ An `AudioMixer` is a project asset, not a scene object, so it is found through t
 rather than a scene query.
 
 ```csharp
-var guids = UnityEditor.AssetDatabase.FindAssets("t:AudioMixer");
+// Scope to Assets. Unscoped, FindAssets also walks read-only packages and reports mixers the
+// user did not author. The second parameter is string[] searchInFolders; there is no SearchMode
+// overload. Measured on one project: t:Material returned 81 unscoped against 9 under Assets.
+var guids = UnityEditor.AssetDatabase.FindAssets("t:AudioMixer", new[] { "Assets" });
 var paths = System.Linq.Enumerable.Select(guids, UnityEditor.AssetDatabase.GUIDToAssetPath);
 return $"count={guids.Length}: {string.Join(", ", paths)}";
 ```