Unity Skills

What It Does

Unity-Technologies/skills is the official Unity org's agent skill pack: 31 skills under skills/, each a SKILL.md prompt contract plus references, covering Unity workflows for AI coding agents. The split is roughly one CLI skill (unity-cli, a 452-line contract over Unity's beta unity CLI), one orchestration skill (new-unity-project, which coordinates installs and handoffs), one UI router (ui, routing to ui-uitk, ui-ugui, ui-imgui), and 27 domain skills spanning render-pipeline migration (migrate-birp-to-urp, 543 lines), physics diagnostics, sprite and tilemap tooling with real C# editor scripts, audio, localization, web and TextMesh optimization, and Unity gaming services (multiplayer, Vivox voice, LevelPlay ads, IAP, cloud save). The audience is developers using Claude Code, Cursor, Codex, Hermes, or any of the 50+ agents the skills.sh installer supports. At review time: 925 stars, 52 forks, 64 commits from 10 contributor accounts led by andresbayon (25) and ziyiunity (20), created 2026-05-05, pushed the morning of review.

The Good

The writing quality is exceptional, and it survives contact with the real binary. The unity-cli skill documents an exit-code table, a JSON envelope contract ("read failures from stdout, not stderr"), 30 environment variables, and pager behavior in more precision than most CLIs document themselves. Every contract claim we could test held: bare unity exits 0, an unknown flag exits 2, unity --version prints 1.0.0-beta.10 exactly as the skill states, and auth status / doctor / editors --installed return the documented success/command/data/errors/warnings envelope shapes. The skill even documents telemetry honestly: anonymous Sentry crash reporting plus one anonymous usage ping per run regardless of consent state, with the opt-out variables named.

The domain skills show real engineering discipline, not prompt filler. migrate-birp-to-urp is a phase-based migration contract that refuses pipeline-mutating work until the user confirms a rollback point, splits "tests failed" from "run did not complete" for CI retry logic, and instructs the agent to prefer an honest phase boundary over an over-claimed complete result. The ui router has a two-step detection ladder (explicit file references first, project sniffing second, ask-or-default third) with explicit route-versus-answer-directly rules. 19 of 31 skills cross-reference siblings by name, so the pack routes rather than duplicating.

There is a functioning internal audit loop. Commit 6da1d12 ("fix: two findings from the agent-skill audit", 2026-09-16) fixed a real bug in a shipped C# helper: the localization batch processor now sorts mapping keys longest-first because dictionary enumeration order is unspecified, which made label binding both wrong and irreproducible. The fix comment explains the failure mode in nine lines. That is a vendor treating skills as software.

Distribution follows the open standard and lands byte-identical. npx skills add Unity-Technologies/skills worked for a Hermes agent target with no adaptation: full skill directories including references and scripts land byte-identical to GitHub, and skills-lock.json is written at the project root. Demand is real: the skills.sh registry carries 29 Unity entries totaling 73,943 installs, with unity-cli at 5,222 and the September cohort (migrate-birp-to-urp, 2d-pixel-perfect, tilemap skills) already at 833 to 895 each.

The Bad

Four of 31 skills ship invalid YAML frontmatter and silently vanish at install. physics-3d-collision, tilemap-ruletile-createfromsegment, ui, and ui-imgui all contain an unquoted colon-space inside their description scalar (for example "Primary scope: OnCollisionEnter" and "when no framework is named: consult this skill"). Every strict YAML parser rejects them ("mapping values are not allowed in this context"), and the skills.sh installer skips each with a one-line warning buried mid-stream. The README's only install command therefore lands 27 of 31 skills. Requesting a broken skill by name (--skill ui) lands nothing, with no error. The worst part: ui is the router the other two surviving UI skills (ui-ugui, ui-uitk) are designed to be reached through, so fresh installs get the specialists without the dispatcher.

Two of those four skills have never been installable from the registry. The skills.sh registry indexes 29 Unity skills; physics-3d-collision and tilemap-ruletile-createfromsegment are absent because their frontmatter was invalid at index time (broken since their birth: PR #55 on 2026-08-13 for physics, PR #42 on 2026-09-08 for tilemap). ui and ui-imgui were indexed before PR #65 ("align six skills with the plugin copy", 2026-09-09) broke them, so the registry serves stale pre-break copies to whoever installs from it. That means GitHub-source installs and registry installs now deliver different skill sets.

There is no CI, and the repo's own audit missed the install-breaking class of bug. .github contains exactly one file: CODEOWNERS. No workflow validates frontmatter, which is how a one-character quoting defect survived 8 days on ui and 35 days on physics-3d-collision at a repo pushing daily. The 2026-09-16 audit commit fixed content bugs 30 lines away from the broken YAML without noticing it. The repo's only eval infrastructure (a 361-line promptfoo suite for setup-vivox-voice-chat with three test files) was deleted the same week (PR #64).

The README does not describe what you are installing. It is 25 lines: a tagline, the install command, three example prompts, and a contributions link. No skill catalog, no per-skill mention, no troubleshooting for the skip warnings, no license explanation beyond a pointer. Combined with no tags, no releases, and no changelog (CONTRIBUTING.md honestly states versioning is just git history), a consumer has no way to notice that four skills went missing.

The license is not open source. LICENSE.md is the Unity Companion License: use is restricted to Unity-dependent projects. Reasonable for Unity, but unlike the MIT/Apache norm of the dotnet, Adobe, Sentry, and gsap vendor packs, and GitHub reports it as NOASSERTION, which will trip automated license checkers.

Smoke Test Results

Host-based runs on macOS 26.5.2 (aarch64), Node 24, executed against a fresh clone at main commit 8d85172 (2026-09-16). The sbx sandbox daemon was down, so the standard scripts ran directly on the host with logs captured to the sandbox paths.

Run A. Fresh sandbox, no deps preinstalled

$ git clone --depth 1 https://github.com/Unity-Technologies/skills # 3.1 MB
✅ clone lands, 31 skill directories
$ for d in skills/*/; do [ -f "$d/SKILL.md" ] || echo "$d"; done | wc -l
✅ 0: SKILL.md present in every skill dir
$ name-vs-folder check across 31 frontmatter blocks
✅ 31 of 31 match
$ for d in skills/*/; do ruby-parse "$d/SKILL.md" frontmatter; done
❌ strict YAML fails for physics-3d-collision, tilemap-ruletile-createfromsegment, ui, ui-imgui
$ linkcheck.py skills/ # all local markdown links
✅ 275 checked, 0 broken
$ grep -c "use when" trigger phrases across descriptions
✅ 25 of 31 trigger-shaped
$ test -f LICENSE.md
✅ present (Unity Companion License)
$ secret-pattern scan across skills tree
✅ 0 hits
$ cross-reference scan (skill names mentioned by sibling SKILL.md bodies)
✅ 19 of 31 skills route to siblings
$ find .github -name "*.yml" -o -name "*.yaml" | wc -l
❌ 0: no CI workflows at all (only CODEOWNERS)

Pass rate: 8 of 10. Both failures are real defects, not test artifacts: the four broken frontmatter blocks reproduce under Ruby's YAML parser, Node's yaml parser (inside the installer), and Python's.

Full sandbox log →

Run B. Sandbox with deps preinstalled

The README-verbatim install, run in an isolated HOME with the hermes-agent target pinned for scripting.

$ npx skills add Unity-Technologies/skills --agent hermes-agent --yes
✅ install command completes ("Done" box)
$ grep "YAML parse error" install-output
✅ 4 skip warnings reported mid-stream (the defect, disclosed but easy to miss)
$ ls .hermes/skills | wc -l
❌ 27 landed of 31 (physics-3d-collision, tilemap-ruletile-createfromsegment, ui, ui-imgui missing)
$ test -f skills-lock.json
✅ lock file written at cwd root
$ diff -r <github-source>/skills/unity-cli .hermes/skills/unity-cli
✅ landed unity-cli skill byte-identical to GitHub source (full dir incl. references)
$ npx skills add Unity-Technologies/skills --agent hermes-agent --skill unity-cli --yes
✅ single-skill install works for a valid skill
$ npx skills add Unity-Technologies/skills --agent hermes-agent --skill ui --yes
✅ silently lands nothing for a broken skill (no error, no files)
$ npx skills add /tmp/unity-fixed --agent hermes-agent --yes # 4 descriptions as block scalars
✅ control: 31 of 31 land with zero parse errors

Pass rate: 7 of 8. The single failure is the headline defect. The control proves the fix is four description lines and nothing else: converting them to >- block scalars in a local copy makes the identical installer land all 31 skills with zero parse errors.

Full sandbox log →

Run C. Functional verification (does it do what it claims?)

The unity CLI installed from the exact URL the skill documents, into an isolated UNITY_CLI_HOME, beta channel, no credentials.

$ curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash
✅ PASS: documented install URL live (HTTP 200, 637-line script)
✅ PASS: unity CLI installs via documented script
$ unity --version
✅ PASS: 1.0.0-beta.10, exactly the version SKILL.md documents
$ unity (bare)
✅ PASS: prints usage and exits 0, as SKILL.md claims
$ unity --definitely-not-a-flag
✅ PASS: exits 2, per the documented exit-code table
$ unity auth status --format json
✅ PASS: documented envelope shape, loggedIn false, no credentials needed
$ unity doctor --format json
✅ PASS: structured checks array (binary-on-path, path-duplicates, ...)
$ unity editors --installed --format json
✅ PASS: documented envelope with empty data array
$ unity skill install --list
✅ PASS: enumerates 8 supported agent clients (claude-code, claude-desktop, grok, cursor, windsurf, vscode, cline, codex)

Functional pass rate: 9 of 9.

Full functional log →

What the runs tell you

The install path works and is faithful (byte-identical landing), and everything the unity-cli skill documents about the CLI itself checked out against the real binary. The pack's problem is concentrated entirely in four frontmatter lines and the absence of any automated check that would have caught them: content 5 stars, packaging 2. The C# editor scripts (59 files, 6,420 lines) were reviewed but not executed; they require a Unity Editor and compile against UnityEditor APIs.

Setup Walkthrough

1. Install the pack: npx skills add Unity-Technologies/skills. Add --agent claude-code or another target if you want a specific host; the default prompts. Expect the progress box to end with "Done" and four ⚠ Skipped ... YAML parse error lines above it.
2. Verify what landed: ls .hermes/skills | wc -l (or your host's equivalent). Today the honest number is 27, not 31. Missing will be physics-3d-collision, tilemap-ruletile-createfromsegment, ui, and ui-imgui.
3. If you need the missing four, patch locally and install from the path: change each broken skill's description: line to a block scalar (description: >- with the text indented two spaces), then npx skills add /path/to/clone. Our Run B control did exactly this and landed 31 of 31. It is a four-line fix Unity has not shipped as of main commit 8d85172.
4. For the CLI itself, follow the unity-cli skill: curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash, then unity --version to confirm. The CLI is beta (1.0.0-beta.10) and reports anonymous crash and usage telemetry unless you set UNITY_NO_CRASH_REPORT; the skill documents both.
5. No Unity account is needed until you touch editors, licenses, or cloud services; unity auth status works unauthenticated and returns clean JSON.

Alternatives

1. Unity-Technologies/unity-agent-plugin - the same vendor's plugin-distribution surface (279 stars), which the skills repo syncs from; use it if your host consumes plugins rather than skills, but note the sync relationship has already propagated breakage in both directions.
2. gamedev-skills/awesome-gamedev-agent-skills - community multi-engine catalog with multiple entries at 2,300 to 2,500 installs each; broader engine coverage, no vendor backing.
3. keijiro/unity-skills - a day-0 community mirror by a well-known Unity graphics developer (6 stars); useful today only as a canary that the ecosystem watches this repo closely enough to mirror it.