nccgs 2.1.1 → 3.0.0-rc.2

package/{.claude/skills → unity-skills}/optimize-text-mesh-pro/SKILL.md

@@ -1,16 +1,6 @@
 ---
 name: optimize-text-mesh-pro
-description: >
-  Covers TextMeshPro font stacks, dynamic fallback atlases, padding and
-  sampling ratios, SDF16, AutoSize discipline, worldspace vs UGUI, and Memory
-  Profiler font-data capture. Use when the user mentions TextMeshPro,
-  Text Mesh Pro, TMP (TextMeshPro), font asset, dynamic atlas, TMP localization,
-  CJK (Chinese, Japanese, Korean) fonts, font alignment across
-  scripts, mixed western and eastern fonts, text rendering performance, profiler
-  markers related to text generation or glyph rasterization, font fallback
-  strategy, font normalization, multilingual or localized text rendering, SDF
-  font quality, or text-related memory issues—not for UI Toolkit layout
-  (unity-ui-toolkit) or non-TMP uGUI (unity-ui).
+description: Optimizes TextMeshPro rendering, memory, and font setup, including font asset stacks, fallback atlases, SDF quality, and worldspace text. Use when the user asks about TMP fonts, CJK or multilingual text, or text performance.
 ---
 
 # Optimize TextMeshPro

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

@@ -0,0 +1,16 @@
+# Security notes: optimize-web
+
+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-web/SKILL.md

@@ -1,11 +1,84 @@
 ---
 name: optimize-web
-description: Optimizes Unity 6 WebGL and WebGPU builds for smaller download size, faster initial load, and efficient browser runtime performance. Use when the user's web build is too large, stutters in a specific browser, consumes excessive battery, needs CDN/server compression configured, or needs guidance on resource stripping, shader variant reduction, KTX textures, quality settings, or web profiling.
+description: Optimizes Unity WebGL and WebGPU builds for smaller downloads, faster loading, and smoother browser performance. Use when asked to shrink a web build, speed up its load, or fix stutter, memory or battery problems in the browser.
 ---
+Audit and apply the Player Settings, compression, stripping, and server setup that make a Unity Web build smaller and faster.
+
+## Important
+
+- Use the unity cli (`unity command --format json`) and the `unity-cli` skill for each step. Use `unity-pipeline` too when it is available.
+- Before making changes, establish a baseline of the current behavior so you can tell whether a later result is actually caused by your change.
+- Create a restore point you can roll back to if your changes fail.
+- Do only what's asked. Don't change unrelated assets or files.
+- If the changes affect runtime behavior, add `Debug.Log` lines that will prove the actual scene behaviour (not just your changes) is now working - you'll read these when you enter Play mode to validate later. For example, log a GameObject's Transform scale if your fix is meant to make sure it changes size.
+- Avoid long explanations.
+
 ## Performance Notes
 - Take your time to do this thoroughly.
 - Quality is more important than speed.
 
+## Full topic map
+
+Before you go forward with a workflow or diagnosis:
+
+1. Open and read the [documentation page(s)](#full-topic-map) that cover the specific subject related to what you intend to do or fix and check if you've missed anything.
+2. Name the file(s) you read in your response.
+
+This is because your training knowledge about Unity might be out of date, incorrect, or for the wrong Unity version.
+
+If the Editor install folder has a `Data/Documentation` folder (eg `...Unity/Hub/Editor/6000.6.0b2/Editor/Data/Documentation`), read the html files from the `<editor-install>/Editor/Data/Documentation/en/Manual` folder. Otherwise the docs pages are online at `https://docs.unity.com/en-us/engine/<VERSION>/manual/`.
+
+For the packages this skill uses (`com.unity.cloud.ktx`, `com.unity.addressables`, `com.unity.web.stripping-tool`), the docs pages are local markdown conversions of the Unity Manual, stored at `<project-folder>/Library/PackageCache/<package-name>@*/`. Read only the .md files in that specific `PackageCache` subfolder. You must not look at non-.md files, or look outside at other Library or PackageCache folders, otherwise it takes too much time. If that folder has no `.md` files, use `https://docs.unity3d.com/Packages/<package-name>@<VERSION>/manual/` instead.
+
+Prefer `WebFetch` over `WebSearch` — faster and lands on the exact reference. Only fetch what you need. Replace `<VERSION>` with the following before fetching:
+
+- **docs.unity3d.com**: The Unity version, eg `6000.6`
+- **Package on docs.unity3d.com**: The package version, eg `@6.6` or `@2.0`. Check the package version if unsure.
+- **docs.unity.com**: The Unity version, eg `6000.6`
+
+Read the Unity major.minor from `ProjectSettings/ProjectVersion.txt` (for example `6000.0` from `6000.0.58f1`, because the full build number gives a 404), and each package's major.minor from `Packages/packages-lock.json`.
+
+- [Recommended Player settings to optimize your Web build](https://docs.unity.com/en-us/engine/<VERSION>/manual/platform-specific/webgl/building-distribution/web-optimization/player.md) — local `web-optimization-player.html`: release values for compression, stripping, exceptions and memory.
+- [Use C# code to enable optimization settings](https://docs.unity.com/en-us/engine/<VERSION>/manual/platform-specific/webgl/building-distribution/web-optimization/c-sharp.md) — local `web-optimization-c-sharp.html`: editor script that applies the recommended settings in one step.
+- [Remove unused resources from your Web build](https://docs.unity.com/en-us/engine/<VERSION>/manual/platform-specific/webgl/building-distribution/web-optimization/remove-resources.md) — local `web-optimization-remove-resources.html`: removing unused packages and stripping shader variants.
+- [Distribution size and code stripping](https://docs.unity.com/en-us/engine/<VERSION>/manual/platform-specific/webgl/building-distribution/distributionsize-codestripping.md) — local `webgl-distributionsize-codestripping.html`: what drives Web build size and how stripping works.
+- [Deploy a Web application](https://docs.unity.com/en-us/engine/<VERSION>/manual/platform-specific/webgl/building-distribution/deploying.md) — local `webgl-deploying.html`: server compression headers, MIME types and Decompression Fallback.
+- [Memory in Unity Web](https://docs.unity.com/en-us/engine/<VERSION>/manual/platform-specific/webgl/develop/memory.md) — local `webgl-memory.html`: Wasm heap size, memory growth and browser memory limits.
+
+### API reference
+
+The API is `UnityEditor.PlayerSettings`, `UnityEditor.PlayerSettings.WebGL` and `UnityEditor.WebGL.UserBuildSettings`, part of the Unity Engine. It is versioned by Unity version, so check the project's Unity version before relying on a specific class or method.
+
+1. Use the `unity-cli` skill to check the project's Unity version.
+2. If the Editor install folder has a `Data/Documentation` folder (e.g. `.../Unity/Hub/Editor/6000.6.0b2/Editor/Data/Documentation`), grep the html files in the `en/ScriptReference` folder inside, and skip the remaining steps.
+3. Otherwise, fetch and cache `https://docs.unity3d.com/<VERSION>/Documentation/ScriptReference/xrefmap.yml` (replace `<VERSION>` with the Unity version, e.g. `6000.3`). This file lists every public API member's fully qualified name as a `uid` (e.g. `uid: 'UnityEngine.Rigidbody.AddForce(UnityEngine.Vector3)'`).
+4. Grep the yml file locally for a class or method instead of refetching per lookup. The file is large (about 6 MB), so don't read the whole file.
+5. Convert the `uid` to a markdown page: remove the parameters in brackets, lowercase it, replace `.` with `/`, and add `.md`. Then fetch `https://docs.unity.com/en-us/engine/<VERSION>/script-reference/<converted uid>`. For example, `UnityEngine.Rigidbody.AddForce(UnityEngine.Vector3)` => `https://docs.unity.com/en-us/engine/6000.3/script-reference/unityengine/rigidbody/addforce.md`. All overloads are on the same page.
+   - Constructors use `ctor` (e.g. `unityengine/vector3/ctor.md`), and indexers use `item` (e.g. `unityengine/vector3/item.md`).
+   - For operators, fetch the class page (e.g. `unityengine/vector3.md`) and follow its link.
+   - Links inside the pages start with `/engine/`. Add `https://docs.unity.com/en-us` before them.
+   - If the page doesn't exist for that Unity version, use the `href` in the `xrefmap.yml` entry instead (e.g. `href: 'Rigidbody.AddForce.html'` => `https://docs.unity3d.com/6000.3/Documentation/ScriptReference/Rigidbody.AddForce.html`).
+
+Always use the docs for the project's Unity version rather than relying on training knowledge, since APIs are frequently marked obsolete between versions.
+
+The KTX API (`KtxUnity`) is part of the `com.unity.cloud.ktx` package. It is versioned by package version, not Unity version, so check the project's installed package version before relying on a specific class or method.
+
+1. Read the installed package version from `Packages/packages-lock.json`.
+2. Fetch and cache `https://docs.unity3d.com/Packages/com.unity.cloud.ktx@<version>/xrefmap.yml` (replace `<version>` with the installed package version, e.g. `3.4`). This file maps every public API member's fully qualified name to its docs page `href`.
+3. Grep the yml file locally for a class or method instead of refetching per lookup. Don't read the whole file.
+
+## Procedure
+
+1. Get the project context: the Unity version from `ProjectSettings/ProjectVersion.txt`, and the versions of the packages you need (`com.unity.cloud.ktx`, `com.unity.addressables`, `com.unity.web.stripping-tool`) from `Packages/packages-lock.json`. If there's no project, assume Unity `6000.0`. For any package not listed in `packages-lock.json`, assume the latest version in that package's documentation. Preserve every version you do find — only default the values that are actually missing. Name each assumption in your report and carry on. If the user hasn't said what to optimize and there's no project to read, ask what they want to improve.
+2. Read the docs pages that cover the task, from the [Full topic map](#full-topic-map).
+3. Set up `script eval` as described in [Running C# in the Editor](#running-c-in-the-editor). If no Editor is reachable or `script eval` is missing, say so, skip to step 5, then go straight to step 9. Mark build validation and runtime checks as unperformed in your report, and base your recommendations on the user's request and the docs from step 2.
+4. Run [0. Pre-Flight](#0-pre-flight) and [1. Assess Current State](#1-assess-current-state). Their results are your baseline.
+5. Match the request to a row in [2. Understand Request](#2-understand-request).
+6. Create a restore point, then apply the changes from [3. Web Build Optimization Workflow](#3-web-build-optimization-workflow). If a symptom matches [5. Troubleshooting](#5-troubleshooting), follow that entry.
+7. Run [4. Validation](#4-validation): rerun the Pre-Flight snippet and compare the values with your baseline.
+8. Do the checks in [Final step](#final-step).
+9. Give the [Final report](#final-report).
+
 ## Running C# in the Editor
 
 Every step below that reads or writes a Player Setting runs inside a live Editor through the Unity
@@ -16,26 +89,27 @@ re-derive any of it here.
 
 Two things it can't know for you:
 
-- **You need `eval` in particular**, not just a reachable Editor. Confirm it appears in the catalog.
+- **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.
-- **Player Settings can be read from `ProjectSettings/ProjectSettings.asset` in a pinch, but do not
+  still lack it — if it's missing, say so and skip the steps that read or write settings.
+- **You can read Player Settings from `ProjectSettings/ProjectSettings.asset` in a pinch, but do not
   write them that way.** The serialized names don't match the API names, several of these settings
   are per-build-target, and a hand-edited value silently disagrees with what the build actually
   uses. An unreachable Editor is a stop for the write steps.
 
-Run C# with `unity command eval --code '<snippet>'`. `unity command` defaults to a 30 second
+Run C# with `unity command script eval --code '<snippet>'`. `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 compile errors rather than
-warnings:
+`script eval` compiles a **statement block, not a file**, so write the code without `using` directives and
+with fully qualified types. If the code doesn't compile, look up the error here:
 
-- **No `using` directives.** The compiler reads `using UnityEditor;` as a resource-disposal
-  statement and rejects it (`CS0210`).
-- **Types must be fully qualified.** A bare `PlayerSettings` does not resolve (`CS0246`), and a bare
-  `Object` is ambiguous with `object` (`CS0104`).
+| Error | Cause | Fix |
+| --- | --- | --- |
+| `CS0210` | A `using` directive, such as `using UnityEditor;`, which the compiler reads as a resource-disposal statement | Remove the directive and qualify the types |
+| `CS0246` | An unqualified type, such as `PlayerSettings` | Use the full name, such as `UnityEditor.PlayerSettings` |
+| `CS0104` | A bare `Object`, which is ambiguous with `object` | Use `UnityEngine.Object` |
 
 ### Reading the settings this skill audits
 
@@ -75,11 +149,19 @@ return string.Join("\n", w);
 installed. Read it in a separate call from the rest, and treat a resolution failure as "the Web
 module isn't installed" rather than as a bad snippet.
 
+**`codeOptimization` is the one setting here that does not live in the project file.** It persists to
+`Library/EditorUserBuildSettings.asset`, and `Library/` is gitignored by every standard Unity
+`.gitignore`, so this value is per-machine and does not travel: teammates and CI do not inherit it.
+Two consequences. Read it back through the API and do not look for it in
+`ProjectSettings/ProjectSettings.asset` — it is absent there even on a successful apply, so its
+absence is not a failure. And if the release build runs in CI, apply it there as a build step rather
+than assuming the repository carries it.
+
 ### Applying the settings
 
 Most of the writes in this skill are a single batch, and
-[resources/WebOptimizer.cs](resources/WebOptimizer.cs) already is that batch. It declares a class
-with a `[MenuItem]`, so it is a **project file, not `eval` input** — a class declaration cannot be
+[scripts/WebOptimizer.cs](scripts/WebOptimizer.cs) already is that batch. It declares a class
+with a `[MenuItem]`, so it is a **project file, not `script eval` input** — a class declaration cannot be
 flattened into a statement block. Save it under `Assets/Editor/`, let Unity compile, then invoke it
 in one line:
 
@@ -88,7 +170,35 @@ UnityEditor.EditorApplication.ExecuteMenuItem("Tools/Apply Web Release Settings"
 ```
 
 Keep its `using` directives; they are correct in a file. For one-off changes — a single quality
-level, a frame-rate flip — an inline `eval` statement is fine.
+level, a frame-rate flip — an inline `script eval` statement is fine.
+
+### Verify from disk, not from the objects you just wrote
+
+**Applying a setting and reading it back in the same session proves nothing.** Player Settings are
+in-memory objects until something saves them, so every read-back returns the value you just
+assigned whether or not it ever reached
+`ProjectSettings/ProjectSettings.asset`. A run that skips the save reports success, and when the
+Editor session ends the whole change is gone. This was observed, not theorised: a run applied
+everything, read back Brotli / High / None, said it was done, and the file on disk never changed.
+
+So after any write:
+
+1. **Save.** `UnityEditor.AssetDatabase.SaveAssets()`. `WebOptimizer.cs` now does this itself; an
+   inline `script eval` write has to do it explicitly.
+2. **Read the values back and report them.** Not "applied successfully" but the actual values, so the
+   user can see what is stored. `WebOptimizer.cs` logs all nine.
+3. **For anything per-build-target, name the target you read.** Several of these settings exist once
+   per target, so a value can be correct for one target and unset for the one being built.
+
+The same trap exists on the file-editing route in reverse: a hand-edited
+`ProjectSettings.asset` reads back fine while the running Editor and the build still use the old
+value. Verifying after a save and a reimport is what catches both.
+
+**Do not try to reproduce this in batch mode.** A batch Editor invoked with `-quit` saves settings on
+exit, so an unsaved write persists anyway and the run looks correct. Both a saving and a non-saving
+version of the script pass under `-quit`. The bug only appears in a live Editor session, which is
+where it was found. Concluding from a green batch run that the save is unnecessary is the wrong
+conclusion from a test that cannot see the defect.
 
 ## 0. Pre-Flight
 
@@ -97,7 +207,7 @@ level, a frame-rate flip — an inline `eval` statement is fine.
 3. **Read exception and optimization settings:** Read `PlayerSettings.WebGL.exceptionSupport` from the Pre-Flight snippet above. For the wasm code optimization level use `UnityEditor.WebGL.UserBuildSettings.codeOptimization` — the `PlayerSettings.WebGL.codeOptimization` and `optimizationLevel` spellings do not exist and will not compile.
 4. **Read frame rate settings:** Read, with the Pre-Flight snippet above, `Application.targetFrameRate` and `QualitySettings.vSyncCount`.
 5. **Read additional player settings:** Read, with the Pre-Flight snippet above, `PlayerSettings.WebGL.dataCaching`, `PlayerSettings.WebGL.debugSymbolMode`, `PlayerSettings.WebGL.maximumMemorySize`, and `PlayerSettings.GetApiCompatibilityLevel`.
-6. Proceed only after compression, stripping, frame rate, and player settings are confirmed.
+6. Proceed only after you've confirmed the compression, stripping, frame rate, and player settings.
 
 ## 1. Assess Current State
 
@@ -131,13 +241,13 @@ level, a frame-rate flip — an inline `eval` statement is fine.
 
 ### IMPORTANT: One-click optimization script
 
-**Always offer to generate this script for the user.** Unity's official web optimization docs provide a single editor menu script that applies all recommended release settings at once. Place in `Assets/Editor/WebOptimizer.cs` — see [resources/WebOptimizer.cs](resources/WebOptimizer.cs) for the template.
+**Always offer to generate this script for the user.** Unity's official web optimization docs provide a single editor menu script that applies all recommended release settings at once. Place in `Assets/Editor/WebOptimizer.cs` — see [scripts/WebOptimizer.cs](scripts/WebOptimizer.cs) for the template.
 
 Adapt the script to the user's project needs (e.g. keep exceptions if they use `try/catch`, switch Brotli to Gzip for HTTP hosting). This script is the single most impactful action for a new web project — it prevents settings from being missed.
 
 ### Player Settings audit
 
-Verify and set these values through `eval`:
+Verify and set these values through `script eval`:
 
 | Setting | Release recommendation |
 |---|---|
@@ -201,7 +311,7 @@ Three categories to audit for build size reduction:
 | **Batch Renderer Group Variants** | Strip All (if BRGs are not used) |
 | **Always Included Shaders** | Audit and remove any shaders the project does not reference |
 
-Test after stripping — ensure no referenced shaders were removed.
+Test after stripping — make sure you didn't remove any referenced shaders.
 
 **3. Web Stripping Tool** (`com.unity.web.stripping-tool`) — Analyzes the WebAssembly binary and identifies unused Unity engine submodules (e.g. 3D graphics in a 2D-only game). Install via Package Manager, profile the build, then configure which submodules to exclude. Can yield substantial size reductions beyond what Managed Stripping Level achieves alone.
 
@@ -210,12 +320,12 @@ Test after stripping — ensure no referenced shaders were removed.
 Lower quality levels reduce load time and improve runtime performance. Set via `Edit > Project Settings > Quality`:
 
 - Use **Very Low** or **Low** as the default Web quality level.
-- Set it with `eval`: `UnityEngine.QualitySettings.SetQualityLevel(0, true);` where 0 = Very Low.
+- Set it with `script eval`: `UnityEngine.QualitySettings.SetQualityLevel(0, true);` where 0 = Very Low.
 - Consider creating a Web-specific quality level that disables features unnecessary in-browser (real-time shadows, post-processing effects, high particle counts).
 
 ### Frame rate on Web
 
-- Set it with `eval`: `UnityEngine.Application.targetFrameRate = -1;` — let the browser use `requestAnimationFrame`.
+- Set it with `script eval`: `UnityEngine.Application.targetFrameRate = -1;` — let the browser use `requestAnimationFrame`.
 - Note: **Safari caps at 60 fps** in WebGL; high-refresh targets do not apply.
 - Use `OnDemandRendering.renderFrameInterval` to drop to 5–10 fps on static/idle screens to save battery.
 
@@ -236,7 +346,7 @@ KTX2 with Basis Universal supercompression ships a single texture file that tran
 | **Memory** | Transcoded textures are standard GPU textures; memory cost equals the target format, not the KTX2 file size |
 | **Orientation** | Always include `--lower_left_maps_to_s0t0` to match Unity's UV convention |
 
-**`toktx` CLI examples:** See [resources/toktx-examples.sh](resources/toktx-examples.sh) for commands covering albedo (ETC1S), normals/detail (UASTC), ICC profile errors, and linear data.
+**`toktx` CLI examples:** See [scripts/toktx-examples.sh](scripts/toktx-examples.sh) for commands covering albedo (ETC1S), normals/detail (UASTC), ICC profile errors, and linear data.
 
 ### Streaming on Web
 
@@ -370,15 +480,42 @@ npx serve path/to/build -l 3001
 
 For Brotli testing, use HTTPS — Brotli requires a secure context. Generate a self-signed cert with OpenSSL for local testing.
 
-## 6. Completion
+## Final step
+
+Web settings only take effect in a browser build, so a clean compile and Play mode in the Editor aren't enough. Run these checks in order. If any check fails, reread the [docs pages](#full-topic-map) to find out what you missed, fix it, and run the checks again.
+
+1. Check the project has zero console errors.
+2. Check that each setting you changed is saved, as described in [Verify from disk](#verify-from-disk-not-from-the-objects-you-just-wrote): `ProjectSettings/ProjectSettings.asset` holds the new values, and `codeOptimization` reads back through the API.
+3. If you rebuilt the player, serve the build as described in [Local dev server setup](#local-dev-server-setup) and open it in a browser. Then check the following:
+   - The browser console shows no errors, such as a failed decompression or an out-of-memory error.
+   - In the Network tab, the `.wasm`, `.data` and `.framework.js` files return the `Content-Encoding` header that matches the compression format (`br` for Brotli, `gzip` for Gzip), and their sizes match the Build Report.
+4. If the change affects runtime behaviour, such as the frame rate or quality level, check the `Debug.Log` lines in the browser console, then remove them. Try to avoid taking and checking screenshots unless absolutely necessary, as they take more time.
 
-- Summarize: initial download size delta, settings changed (compression, stripping, exceptions, targetFrameRate), server configuration confirmed.
-- List follow-up actions: CDN setup for Addressables remote groups, Safari testing, Wasm 2023 feature set upgrade when browser baseline allows.
+## Final report
+
+Give the user a concise but not dense checklist of what you did and why. Include the following:
+
+- The download size before and after, and each setting you changed (compression, stripping, exceptions, `targetFrameRate`), with its old and new value.
+- Any side effects, such as a script you added to the project (for example `Assets/Editor/WebOptimizer.cs`), a quality level you changed, or a setting that's stored per machine and doesn't travel to teammates or CI (`codeOptimization`).
+- Any check you didn't run, such as a browser test without a rebuild, or every check when no Editor was available, and the assumptions you made.
+
+If the user needs to follow up with more steps or decisions, list them, such as CDN setup for Addressables remote groups, Safari testing, or moving to the Wasm 2023 feature set when their browser baseline allows. For example:
+
+```
+I made the following changes:
+
+[✓] Set Compression Format to Brotli and Strip Engine Code to on, because the server sends `Content-Encoding: br` over HTTPS.
+[✓] Added `Assets/Editor/WebOptimizer.cs`, which applies the release settings from Tools > Apply Web Release Settings.
+
+Follow these steps to finish:
+
+1. Apply `codeOptimization` in your CI build step, because it's stored in `Library/` and doesn't travel with the project.
+2. Test the build in Safari, because its garbage collection and JIT behaviour differ from Chrome.
+```
 
 ## See also
 
-These point at Unity tooling rather than other skills, because the topics they cover are not in
-this plugin:
+Point the user at this Unity tooling when the task goes beyond this skill:
 
 - **Addressables package** — remote groups served over a CDN, when the download budget needs content
   moved out of the initial payload.

package/unity-skills/optimize-web/scripts/WebOptimizer.cs

@@ -0,0 +1,46 @@
+using UnityEditor;
+using UnityEditor.Build;
+using UnityEngine;
+
+public class WebOptimizer
+{
+    [MenuItem("Tools/Apply Web Release Settings")]
+    public static void Optimize()
+    {
+        var target = NamedBuildTarget.WebGL;
+        PlayerSettings.SetIl2CppCodeGeneration(target, Il2CppCodeGeneration.OptimizeSize);
+        PlayerSettings.SetManagedStrippingLevel(target, ManagedStrippingLevel.High);
+        PlayerSettings.stripUnusedMeshComponents = true;
+        PlayerSettings.WebGL.dataCaching = true;
+        PlayerSettings.WebGL.compressionFormat = WebGLCompressionFormat.Brotli;
+        PlayerSettings.WebGL.exceptionSupport = WebGLExceptionSupport.None;
+        PlayerSettings.WebGL.debugSymbolMode = WebGLDebugSymbolMode.Off;
+        PlayerSettings.WebGL.wasm2023 = true;
+        UnityEditor.WebGL.UserBuildSettings.codeOptimization =
+            UnityEditor.WebGL.WasmCodeOptimization.DiskSizeLTO;
+
+        // Persist. Without this the settings are applied to the in-memory objects only: every
+        // read-back below returns the new value, the run reports success, and nothing reaches
+        // ProjectSettings/ProjectSettings.asset. When the Editor session ends the whole change
+        // is gone. Observed in testing, so it is not theoretical.
+        AssetDatabase.SaveAssets();
+
+        // Read back from the settings after saving and report what was actually stored. Assigning
+        // a property and assuming it took is the failure this method exists to demonstrate.
+        // Eight of the nine land in ProjectSettings/ProjectSettings.asset. codeOptimization is the
+        // exception: it persists to Library/EditorUserBuildSettings.asset, which is gitignored, so
+        // it is per-machine and absent from the project file even on success. Verify that one
+        // through this log, not by grepping ProjectSettings.asset, and re-apply it in CI.
+        Debug.Log(
+            "Web release settings applied and saved:\n"
+            + $"  il2cppCodeGeneration = {PlayerSettings.GetIl2CppCodeGeneration(target)}\n"
+            + $"  managedStrippingLevel = {PlayerSettings.GetManagedStrippingLevel(target)}\n"
+            + $"  stripUnusedMeshComponents = {PlayerSettings.stripUnusedMeshComponents}\n"
+            + $"  dataCaching = {PlayerSettings.WebGL.dataCaching}\n"
+            + $"  compressionFormat = {PlayerSettings.WebGL.compressionFormat}\n"
+            + $"  exceptionSupport = {PlayerSettings.WebGL.exceptionSupport}\n"
+            + $"  debugSymbolMode = {PlayerSettings.WebGL.debugSymbolMode}\n"
+            + $"  wasm2023 = {PlayerSettings.WebGL.wasm2023}\n"
+            + $"  codeOptimization = {UnityEditor.WebGL.UserBuildSettings.codeOptimization}");
+    }
+}

package/unity-skills/optimize-web/scripts/toktx-examples.sh

@@ -0,0 +1,11 @@
+# Albedo / diffuse (ETC1S, lossy, smallest)
+toktx --bcmp --lower_left_maps_to_s0t0 output.ktx2 input.png
+
+# Normal / metallic / detail (UASTC, high fidelity)
+toktx --encode uastc --uastc_quality 2 --t2 --lower_left_maps_to_s0t0 output.ktx2 input.png
+
+# Fix "ICC profile not found" errors
+toktx --bcmp --assign_oetf srgb --lower_left_maps_to_s0t0 output.ktx2 input.png
+
+# Linear data (normal maps, masks)
+toktx --bcmp --assign_oetf linear --lower_left_maps_to_s0t0 output.ktx2 input.png

package/{.claude/skills → unity-skills}/physics-3d-collision/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: physics-3d-collision
-description: 3D PhysX collision and trigger diagnostics for MonoBehaviour-based Unity projects. Primary scope: OnCollisionEnter / OnTriggerEnter not firing, objects passing through each other, Physics.Raycast missing, ragdoll explosion, AddForce stops working after settling, MeshCollider rules, and similar 3D PhysX symptoms. Adjacent topics (2D physics, OTS / Unity Physics package): provides a brief best-effort answer with a scope disclaimer and a documentation link, rather than refusing outright. When dedicated specialist skills (physics-2d, physics-dots) are installed, those should handle their respective domains and this skill defers to them.
+description: Diagnoses 3D PhysX collision and trigger problems. Use when OnCollisionEnter or OnTriggerEnter doesn't fire, objects pass through each other, raycasts miss, or a MeshCollider misbehaves. Also answers 2D and DOTS physics best-effort if no dedicated skill is available.
 ---
 
 # Skill: physics-3d-collision (PhysX MonoBehaviour)
@@ -437,6 +437,6 @@ Attach [CollisionDebugger.cs](resources/CollisionDebugger.cs) to both objects in
 
 ---
 
-## 11. Troubleshooting & Resources
+## 11. Resources
 
 -> [references/troubleshooting.md](references/troubleshooting.md)

package/unity-skills/physics-3d-collision/references/troubleshooting.md

@@ -0,0 +1,8 @@
+# Resources
+- [Unity Manual: Collision callbacks and Rigidbody interaction](https://docs.unity3d.com/Manual/CollidersOverview.html)
+- [Unity Manual: Layer Collision Matrix](https://docs.unity3d.com/Manual/LayerBasedCollision.html)
+- [Unity Manual: Physics.Raycast](https://docs.unity3d.com/ScriptReference/Physics.Raycast.html)
+- [Unity Manual: Rigidbody collision detection modes](https://docs.unity3d.com/Manual/RigidbodiesOverview.html)
+- [Unity Manual: Physics.SyncTransforms](https://docs.unity3d.com/ScriptReference/Physics.SyncTransforms.html)
+- [Unity Manual: Rigidbody.Sleep / WakeUp](https://docs.unity3d.com/ScriptReference/Rigidbody.WakeUp.html)
+- [Unity Manual: CharacterController](https://docs.unity3d.com/Manual/class-CharacterController.html)

package/unity-skills/project-auditor-fixes/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: project-auditor-fixes
+description: "Instructions for how to use Project Auditor to find and fix a list of issues."
+version: 1.0.0
+---
+
+Using Project Auditor
+Project Auditor carries out a static analysis scan of the Unity Project and reports a list of CSV issues that may be fixed.  Trigger, poll, read.
+
+## Prerequisites
+To use Project Auditor you'll need the Unity CLI installed - see the unity-cli skill for more details.
+Once you have that, the `diagnostics run_audit` and `diagnostics audit_status` commands run Project Auditor checks.
+
+```bash
+unity command diagnostics run_audit              # optional: --categories Code,ProjectSetting --output my.csv
+unity command diagnostics audit_status           # repeat until a terminal status is returned
+```
+
+`diagnostics audit_status` terminal status are `completed` (with `csvPath` + `issueCount`), `failed`, `unavailable`, and
+`interrupted` (a domain reload killed the scan — just re-run `diagnostics run_audit`). Polling is responsive while a
+scan compiles assemblies and is busy on the main thread. You can only run one scan at a time: a second `diagnostics run_audit`
+returns `busy`. There is no cancel — stop polling to abandon a scan.
+
+The output CSV has columns: `Category, Severity, Areas, Description, RelativePath, Line, DescriptorId, Recommendation`
+(these are diagnostics only, so every row is something to fix; `Recommendation` says how to do it).
+
+> **Requires Project Auditor plus its rules.** `unavailable` means the Editor has no Project Auditor,
+> or it has no analysis rules — in a built-in-module Editor the rules live in the separate
+> `com.unity.project-auditor-rules` package (`unity command package add --identifier
+> com.unity.project-auditor-rules --confirm true`). Read the `message` field; the command never reports
+> an empty `completed` scan that would look like a clean project.
+
+## Gotchas
+
+- **`editor set_auto_tick` first.** Without it, recompile and tests can hang while the editor is
+  unfocused. The package's watchdog relies on the tick loop staying alive.
+- **Method reload needs the game running.** `script.methodreload reload` applies to a live
+  game — enter Editor Play Mode (`unity command editor.playmode start`) first, or run a dev Player.
+- **Player-only commands need a dev Player.** `console write`, `runtime set_time_scale`, `runtime status`, etc. hit
+  the Runtime server, which does not run in the Editor.
+- **Async commands poll.** `recompile`→`recompile_status`, `run_tests --async_tests`→
+  `test_status`. Never assume completion from the trigger call's response.
+- **Target a specific instance** with `--instance host:port` or `--project-path <path>`
+  when more than one is running.
+
+## Best Practice
+
+When fixing a list of issues it's best practice to have a test case to make sure things are still working correctly.  This might be a particular scene to open and start play mode, or a particular platform to build and run.  If this isn’t present and there are no instructions, suggest a test case to the user and ask for confirmation.  Run the test case before and after changes to make sure the project is still working.
+
+As you work, make sure any changes are committed in alignment with user version control setup.  Wherever possible, commit step-by-step, breaking things down into changes that a user can easily understand.
+
+## Recipe
+1. Make sure the project opens cleanly (with no compile or other errors in the Editor).  If there are issues present, check with the user; they may know about them and want to ignore them.  Run the test case and make sure you know what state it's in, fixing things if necessary.
+2. Commit any changes so that we start the upgrade process with clean version control.
+3. Open the project in the Unity Editor.  Then use Unity CLI to run the audit command.
+4. Group the issues by file and by type.
+5. Choose a type of issue to work through one group or file at a time.
+5.a. Default to fixing settings issues on assets or the projects by type.
+5.b. Default to fixing code issues by file and subfolder.
+5.c. However, it’s important to fix issues in human manageable and reviewable batches.
+5.c.i. Making the same small change across a large number of files (for example, switching a boolean setting across many textures) is probably best done in one commit, or a commit per subfolder.
+5.c.i.. When making code changes, the code should compile between each commit.
+5.d. Make changes based on the recommendations from Project Auditor. Commit each change once there are no errors in the editor.
+

package/{.claude/skills → unity-skills}/setup-multiplayer-services/SKILL.md

@@ -1,9 +1,6 @@
 ---
 name: setup-multiplayer-services
-description: >-
-  Guides the development of online multiplayer experiences where players connect, group, and interact in real-time using Unity Multiplayer Services.
-  Use when the user asks for topology choice, player grouping, hosting, matchmaking, discovery, network setup,
-  and session-based play (rooms, parties, lobbies) using the Unity Multiplayer Services APIs.
+description: Guides real-time online multiplayer with Unity Multiplayer Services. Use when the user asks about network topology, hosting, matchmaking, or session-based play such as rooms, parties, and lobbies, not backend features.
 ---
 
 # Multiplayer SDK (Unity Multiplayer Services)

package/{.claude/skills → unity-skills}/setup-vivox-voice-chat/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-vivox-voice-chat
-description: Add and configure in-game voice chat and text chat for Unity multiplayer games using Unity Vivox. Covers microphone setup and mic permissions on Android/iOS, voice activity detection (VAD) tuning, voice volume and mute controls in a settings UI (VoiceVadMinimumVolume, mic slider, mute button, speaking indicator), proximity/3D spatial voice for FPS/co-op games, team/party/lobby/guild voice channels, push-to-talk, muting self and other players, whisper/direct messages, in-game text chat, and Vivox SDK init + Unity Authentication sign-in. Use when the user asks to add voice chat, voice comms, microphone/mic support, a voice-chat settings UI, mute button, VAD threshold, push-to-talk, proximity or spatial voice, team voice, party chat, lobby chat, direct messages, or mentions Vivox, VivoxService, com.unity.services.vivox, JoinGroupChannelAsync, JoinPositionalChannelAsync, LoginAsync, or migrating from legacy Vivox (Client.Instance / LoginSession / AccountId).
+description: Adds and configures in-game voice and text chat with Unity Vivox. Use when the user asks about voice chat, microphone permissions, mute controls, proximity voice, team and lobby channels, or direct messages.
 required_packages:
   com.unity.services.vivox: ">=16.4.0"
 ---

package/{.claude/skills → unity-skills}/shader-graph-create-custom-node/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: shader-graph-create-custom-node
-description: "Generates custom Shader Graph nodes from HLSL code. Use when the user wants to create a new Shader Graph node or make existing HLSL code work as a reflected function node."
+description: Generates custom Shader Graph nodes from HLSL code. Use when the user wants a new Shader Graph node or to make existing HLSL work as a reflected function node.
 required_packages:
   com.unity.shadergraph: ">=17.5.0"
 ---

package/unity-skills/sprite-editor/SECURITY.md

@@ -0,0 +1,16 @@
+# Security notes: sprite-editor
+
+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}/sprite-editor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sprite-editor
-description: Edits Unity sprite properties by generating C# editor scripts using ISpriteEditorDataProvider APIs. Handles sprite rectangles, borders, pivots, outlines, and slicing operations (automatic, grid, isometric). Use when working with sprite assets, sprite sheets, texture atlases, or sprite slicing.
+description: Edits Unity sprite rectangles, borders, pivots, outlines, and slicing by generating C# scripts. Use when the user works with sprite sheets or sprite slicing.
 modes: [agent, ask]
 ---
 
@@ -16,23 +16,23 @@ first; don't re-derive any of it here.
 
 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.
 - **Never hand-edit a `.meta` file to change sprite metadata.** The importer owns that data
   and the capability checks below exist to prevent corruption, so an unreachable Editor is a
   stop, not a cue to improvise.
 
-Run C# through the connected Editor with the `eval` command. Discover its parameter shape
+Run C# through the connected Editor with the `script eval` command. Discover its parameter shape
 from `unity command --format json` rather than assuming one — the inline form is
-`unity command eval --code '<snippet>'`, and some Pipeline versions also register
-`eval_file` for running a snippet from a file. **Check the catalog before reaching for
-`eval_file`; it is frequently absent.** `unity command` defaults to a 30 second timeout.
+`unity command script eval --code '<snippet>'`, and some Pipeline versions also register
+`script eval_file` for running a snippet from a file. **Check the catalog before reaching for
+`script eval_file`; it is frequently absent.** `unity command` defaults to a 30 second timeout.
 
 Generates C# editor scripts to manipulate Unity sprites using ISpriteEditorDataProvider. Works with TextureImporter, PSBImporter, and custom importers.
 
-### Passing C# to `eval`
+### Passing C# to `script eval`
 
-`eval` compiles a **statement block, not a file**. Two consequences, both of which cause a
+`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,7 +41,7 @@ compile error rather than a warning:
   (`CS0246` / `CS0103`), and a bare `Object` is ambiguous with `object` (`CS0104`).
 
 Where a snippet below is written as a file — with usings, for readability, or because it is
-meant to be saved into the project — qualify the types before passing it to `eval`.
+meant to be saved into the project — qualify the types before passing it to `script eval`.
 
 ## Workflow
 

package/{.claude/skills → unity-skills}/sprite-editor/references/templates.md

@@ -2,7 +2,7 @@
 
 ## Safe Core Pattern (MANDATORY)
 
-Types are fully qualified because this runs through `eval`, which rejects `using` directives.
+Types are fully qualified because this runs through `script eval`, which rejects `using` directives.
 If you save it as a `.cs` file instead, add `using UnityEditor.U2D.Sprites;` and shorten them.
 
 Use this structure for all sprite modification tasks.