Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions skills/new-unity-project/SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,17 @@

This skill has the agent install Unity Editors and packages, create a cloud-linked project, run C#
inside the user's Editor (the visual baseline), write one small bootstrap script into the project,
and append one line to the project's CLAUDE.md or AGENTS.md. Automated skill scanners flag several
of these as powerful capabilities. They are intentional, and limited by the safeguards below.
append one line to the project's CLAUDE.md or AGENTS.md, and — only on the user's yes — upload a
WebGL build to Unity Play as a public listing. Automated skill scanners flag several of these as
powerful capabilities. They are intentional, and limited by the safeguards below.

## Accepted risks

| Risk | Capability | Why it is accepted |
|---|---|---|
| `SEC_POWER_CAP` | Runs C# in the user's Editor | It only reaches the Editor the user already has open, on their own machine, as that user; the commands sit behind the Pipeline capability gate. No code fetched from a remote source is run — the agent runs C# it writes from this skill's and its delegated skills' own recipes. |
| `SEC_FILE_WRITE` | Writes one bootstrap script (Step 6) and appends one line to CLAUDE.md/AGENTS.md (Step 9) | Both writes land inside the project the skill just created and both are surfaced before they run: in paved mode as notice with an opt-out on the assumptions manifest ("say the word to change any of these"), in guided mode as per-step asks that are true consent. Both are reversible on a word, and the scope section caps the skill at exactly one bootstrap script. |
| `SEC_FILE_WRITE` | Writes one bootstrap script (Step 6) and appends one line to CLAUDE.md/AGENTS.md (Step 11) | Both writes land inside the project the skill just created and both are surfaced before they run: in paved mode as notice with an opt-out on the assumptions manifest ("say the word to change any of these"), in guided mode as per-step asks that are true consent. Both are reversible on a word, and the scope section caps the skill at exactly one bootstrap script. |
| `SEC_PUBLISH` | Uploads a WebGL build to Unity Play as a public listing on the user's account (Step 10) | Publishing is a human gate that is never consumed: the agent asks once after Step 9's commit, says plainly that a yes uploads the scene as it currently stands publicly (Step 9's playable loop on the paved path, the raw template on a `--bare` run), and waits. The upload runs only through the CLI's own publishing command on the signed-in account — network egress of the build and nothing else — and its confirmation flag is passed only because the user just answered that same question. An editing URL in the result is handed over as the author's page to finish, never presented as a playable link, and an accepted upload is never retried (a retry would create a second public listing); a timeout or unclear outcome is reported as uncertain and checked on the user's listings page, never retried blind. |
| `SEC_INSTALL` | Installs Editors, modules, packages, and (with the user's yes) agent skills | Installs go through the Unity CLI's own commands and the PackageManager API — never `curl \| sh`, never hand-edited manifests. Skill installs always ask first (Before Step 1). Versions and the package list are declared before installing. |
| `SEC_CLOUD` | Creates a cloud-linked Unity project with diagnostics per the CLI's defaults | The link is `projects create`'s own default behavior, narrated to the user from the create result. Sign-in is a human gate: it runs only after the user's yes, and the user completes it in the browser. `--bare` and the link opt-outs are honored on the user's word. |

Expand Down
358 changes: 132 additions & 226 deletions skills/new-unity-project/SKILL.md

Large diffs are not rendered by default.

23 changes: 23 additions & 0 deletions skills/new-unity-project/references/checklist.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Checklist — new-unity-project reference

Tick every line before the Final report.

- [ ] 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,
settings read back with `script eval` (skipped on `--bare`; on 6000.5.0–6000.5.2, Editor updated first)
- [ ] `.meta` files exist; first commit made; `Library/` excluded
- [ ] At least one playable loop closed (floor 7, or the user's stated shape), the done gate run on
the build, and the build committed (skipped on `--bare`)
- [ ] Publish asked once after the Step 9 commit, never assumed; on a yes, the Unity Play link in
the report (the gap named on CLI versions without `publish`)
- [ ] Forward baton offered and written only on a yes (none on `--bare`); handoff done if applicable
19 changes: 19 additions & 0 deletions skills/new-unity-project/references/common-mistakes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Common mistakes — new-unity-project reference

- **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.
- **Stopping at the baseline** — a project that renders but doesn't play leaves the done gate
nothing to score. The opposite slip: piling on content before the first loop closes.
- **Publishing on an assumption, or not asking at all** — the link is the flow's last leg, and
it's a human gate in both directions: never uploaded without a yes, never silently dropped.
33 changes: 33 additions & 0 deletions skills/new-unity-project/references/join-and-terms.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Step 3: join the create, reconcile, accept terms — new-unity-project reference

### Contents

- Read the create result and reconcile it with the manifest
- Install modules when the Editor was already present
- Accept the Editor Software Terms

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.

**Once create succeeded, accept the Editor Software Terms before any open, and only after the
user's yes.** If the terms question is still unanswered, wait for the answer before running
anything. If the user declined, don't run `unity terms accept`: stop before the first open and say
the Editor won't start past its terms dialog. On a yes, run
`unity terms accept <data.version> --architecture <data.architecture> --yes` with no Editor running
(a running Editor can overwrite the answer). It reports `alreadyAccepted: true` and writes nothing
when they are already recorded. Do the same for any Editor the run moves to later, such as the
6000.5.3+ update in Step 7. If `unity status --until-ready` after an open reports
no instance while the Editor process is running, check `unity terms status <version> --architecture <architecture>`: a
`not-accepted` Editor is sitting on that dialog, which only the user can click.

44 changes: 44 additions & 0 deletions skills/new-unity-project/references/packages-and-identity.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Packages and player identity (Steps 5 and 6) — new-unity-project reference

The detail behind the main skill file's Steps 5 and 6. Read it before either step.

## 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 and lighting with the baseline (Step 7), then camera, character motion, the
playable loop, feedback, audio, shell, live floor, and its done gate (Step 9).
Its values supersede the skill's own fallbacks (`visual-baseline.md` items 1 to 6 and the main
skill file's Step 9 loop) whenever present, version skew included. Missing
and declined → fallbacks, gap named in the report.

41 changes: 41 additions & 0 deletions skills/new-unity-project/references/publish.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Publish to Unity Play (Step 10) — new-unity-project reference

### Contents

- The human gate
- Confirm the CLI offers publishing
- Build WebGL
- Upload and read the result

The flow's last leg is a link someone can play, because a project that exists only on this machine
hands the user nothing to show. **Publishing is a human gate** (the Mode contract): after Step 9's
commit, ask once whether to upload the project to Unity Play, and wait — the upload is
public-facing and runs on the user's account, so it is never assumed, in paved mode included. Say
plainly what a yes uploads at this point — describe the scene as it actually stands: on the paved
path that is Step 9's playable loop as its done gate scored it, on a `--bare` run the raw
template (not yet a game, so that listing is only a pipeline receipt). On a yes, in order:

1. **Confirm the CLI offers it**: run `unity --help` and look for a publishing command group.
Most installed CLIs have none yet — then say so, point the user at the WebGL Publisher package
as the manual route, with `<VERSION>` the package version, eg `4.2` (check it if unsure; the site has no `.md` variant)
(https://docs.unity3d.com/Packages/com.unity.connect.share@<VERSION>/manual/index.html), record the
gap in the report, and never drive the Editor UI to publish on the user's behalf.
2. **A WebGL build is the input.** WebGL has no built-in command-line build, so it takes a build
profile: `unity build --create-profile WebGL` once, then `unity build --profile "Assets/Settings/Build
Profiles/WebGL.asset" --output-path <dir>` (the `webgl` module must be installed — Step 2's
modules, else `unity install-modules`).
3. **Upload through that publishing group's own command** — read its `--help` first; it takes the
build directory, zips and uploads it on the signed-in account, and asks its own confirmation,
which is the same human gate the user just answered, so pass the confirmation flag its help
names. Read the result with `--format json`: `url` is the listing and `urlKind` says what kind —
`listing-edit` is the author's editing page, not a playable link, so hand it to the user as
"finish the listing here" and present a playable URL only once they have. The command's errors
are self-contained (sign-in, a non-WebGL folder, the size limit) and name the fix: run the
named fix and retry only when the failure clearly came before the upload was accepted — after
acceptance, every invocation uploads again and creates a second listing, so report the accepted
upload for inspection instead of retrying. A timeout or dropped connection is neither: the
upload may have been accepted anyway, so do not retry — report the outcome as uncertain and ask
the user to check their Unity Play listings before any second attempt.

A declined publish is a one-line note in the report with the route to run later, never a nag.

21 changes: 21 additions & 0 deletions skills/new-unity-project/references/sign-in-details.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Sign-in and license details — new-unity-project reference

### Contents

- Rules for signing in and activating
- Declining

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

5 changes: 3 additions & 2 deletions skills/new-unity-project/references/skill-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,9 @@ the installer put it and read the skill file from there.
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.
the package, otherwise `<project-folder>/Library/PackageCache/com.unity.pipeline@*/`. List
`Library/PackageCache` for the exact name, since the suffix is often a hash, not the version. Read
only `.md` files, and only from that one package folder.

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
Expand Down
Loading
Loading