Unity skill package setup

Run once per project. Everything it writes lives in the user's Unity repo, so nothing here happens without asking — you are creating tracked files and a folder layout the whole team inherits.

Safe to re-run: every step checks what is already there and adds only what is missing.

1. Find the project and see what already exists

PV=$(find . -path '*/ProjectSettings/ProjectVersion.txt' -not -path '*/Library/*' -print -quit)
ROOT=$(dirname "$(dirname "$PV")")           # the Unity project
REPO=$(git rev-parse --show-toplevel)        # the repo — often one level up
echo "unity project: $ROOT"
echo "repo root    : $REPO"
ls "$REPO/CLAUDE.md" "$REPO/AGENTS.md" "$REPO/STRUCTURE.md" "$REPO/.claude/settings.json" 2>/dev/null
ls -d "$ROOT/Assets"/*/ 2>/dev/null

CLAUDE.md, AGENTS.md and STRUCTURE.md go at the repo root, not the Unity project root, because that is where Claude Code reads them. They often differ — a Unity project frequently sits one directory down.

If any of those files already exist, read them before writing anything. Never overwrite a file someone wrote by hand. Show the user what you would add and let them choose: merge the new sections in, or leave it alone.

2. Preflight the project

Check, report, and let the user decide. Do not fix these silently — each one rewrites or reconfigures their project:

• Serialization mode. m_SerializationMode: 2 in ProjectSettings/EditorSettings.asset. Anything else and scenes and prefabs are unmergeable binary. This is the single most valuable thing to fix at setup time — but flipping it re-serializes every asset in the project, so it is the user's call and it wants its own commit.
• Editor version, from ProjectVersion.txt. It decides which path the other skills use: 6.0+ can drive a running editor, older is batch mode only.
• Render pipeline — Built-in, URP or HDRP. It changes what a material or a shader asset fundamentally is, so it belongs in the generated CLAUDE.md. Read the graphics settings and the package manifest.
• Assembly definitions. Count the .asmdef files. None means every script change recompiles the whole project, which is the difference between a two-second and a forty-second edit loop and taxes every batch run and every worker. Report it — adding them restructures compilation and is a task of its own, not a setup step.

Report all of it in one message rather than asking four times.

3. Git hygiene

Read references/git-hygiene.md. Two things decide whether this repo is workable at all.

.gitignore — check what git actually does, with git check-ignore, not what the file says. Library/, Temp/, Obj/, Logs/, Build/, MemoryCaptures/ and UserSettings/ must be ignored; every asset and every .meta under Assets/, at any depth must be tracked.

An ignored .meta is the highest-priority finding this skill can produce: assets arrive without their GUIDs on a fresh clone and every reference to them silently breaks. Say so plainly and before anything else.

Show additions to an existing .gitignore; never replace one. Offer Unity's standard template only when the file is missing entirely.

Scene merging — offer to wire up Unity's YAML-aware merge tool via .gitattributes. Ask first: it adds a tracked file and changes git config. Note that the .gitattributes half is shared but the git config half is per-clone, so each teammate runs it themselves.

4. Install the plugin at project scope

Ask first — it writes .claude/settings.json, a tracked file everyone who clones inherits.

claude plugin marketplace add Xenoneqq/unity-ai-skills --scope project
claude plugin install unity-ai-skills@unity-ai-skills --scope project

That commits the marketplace and the enabled plugin to the repo and copies nothing, so the whole team gets the skills and claude plugin update keeps them current. Say that the resulting .claude/settings.json should be committed.

If the user would rather keep it personal, drop --scope project — then the skills are theirs alone and the generated CLAUDE.md still documents the routing for everyone else.

Which branch to follow, in the same question: main, the stable version (recommended), or experimental, where changes are tried before they reach main. For experimental, add the marketplace as Xenoneqq/unity-ai-skills#experimental. To switch an existing install, at the same scope:

claude plugin marketplace remove unity-ai-skills          # also uninstalls the plugin
claude plugin marketplace add Xenoneqq/unity-ai-skills#experimental --scope project   # or no #ref for main
claude plugin install unity-ai-skills@unity-ai-skills --scope project

Say that the switch reaches a session only after /reload-plugins or a new session, and record the branch in the generated CLAUDE.md. Skill names stay the same on both branches, so the routing table does not change.

5. Connect the editor CLI

Agents run Unity in batch mode by default: the editor stays closed, builders and tests run headless through unity run and unity test, and nothing opens a window or takes the user's focus (unity-scene-habits, references/batch-mode.md). That works on any editor version. The Unity CLI's Pipeline package is still worth installing, for the jobs that need a live editor and for opening the editor when the user wants to test. Installing it is a one-time step per project, so it belongs here rather than in the middle of someone's task.

It needs the unity CLI and an editor 6.0 or newer. On an older project, skip this step and say agents will use batch mode only. Without the CLI, say so and point the user at Unity's documentation for installing it; do not install it for them. Batch mode then uses the raw editor binary.

command -v unity && unity pipeline list --json --no-banner
grep -n '"com.unity.pipeline"' "$ROOT/Packages/manifest.json" || echo "pipeline package not installed"

Ask first. It adds com.unity.pipeline to Packages/manifest.json and packages-lock.json, tracked files the whole team inherits, and it is an experimental package.

The install has to run with the project closed. Unity reads the manifest when it loads the project, and the install refuses a project an editor has open, failing with PIPELINE_MANIFEST_WRITE_FAILED. If unity pipeline list shows an editor on this project, ask the user to save and close it themselves. Never close it for them: unity close exits without saving. Then install into the Unity project, which is not always the repo root:

unity pipeline install --project-path "$ROOT"
grep -n '"com.unity.pipeline"' "$ROOT/Packages/manifest.json"

The grep is the check that it landed. When the user next opens the project, unity pipeline list shows the editor with Pipeline available. unity-scene-habits has what the connected path can do and how to read its results.

Mute batch runs

Batch PlayMode tests still play sound through the user's speakers. Offer the one-file editor script from unity-scene-habits' references/batch-mode.md ("Mute batch runs"): it mutes only batch editors and puts the user's own mute setting back afterwards, since Unity stores that setting globally. If the project already has an older version that only mutes, replace it. It is a tracked file, so ask, and put it in the project's editor-tools folder if it has one.

ProBuilder, for a 3D game

unity-level-design blocks levels out best with ProBuilder: textures line up across walls of any length, doorways are real openings, and a person can push faces around afterwards. It is a 3D tool, so ask whether the game is 3D rather than deciding it. Detect a guess first and put it in the question:

grep -oE '"com\.unity\.(probuilder|feature\.2d|2d\.[a-z.]+)"' "$ROOT/Packages/manifest.json"

2D packages suggest a 2D game, but many 3D projects carry them too, which is why this is a question and not a rule. If the game is 3D and ProBuilder is missing, offer it in the same question, with the cost in one line: its meshes serialize into prefabs, so their files grow.

It is a package decision like Pipeline, and it installs the same way, with the project closed. Do both in the same closed window so the user closes the editor once. unity-scene-habits' references/batch-mode.md has the Package Manager recipe; the package id is com.unity.probuilder. A declined offer is fine: the level skill falls back to primitives. Record the answer, and Pipeline's, in the generated CLAUDE.md, so no later skill asks again.

A PlayMode test assembly

End-to-end PlayMode tests driven through the game's public API beat the ad-hoc play-tests through eval that every worker otherwise rewrites. Check whether the project has one:

find "$ROOT/Assets" -name '*.asmdef' -not -path '*/ThirdParty/*' -print0 |
  while IFS= read -r -d '' f; do
    grep -qE 'UNITY_INCLUDE_TESTS|TestAssemblies' "$f" || continue
    grep -q '"Editor"' "$f" && echo "EditMode tests: $f" || echo "PlayMode tests: $f"
  done

If there is none, offer one in the same question as the packages. Its tests can only reference game code that lives in an assembly definition of its own. When the code is not in one yet, moving it is a task for the backlog (Step 2), not a setup step, so offer the test assembly as part of that task. Real input and game feel stay manual checks either way. unity-coding-habits has how to write the tests.

6. Scaffold the asset folders

Read references/folder-scaffold.md for the default tree, what each folder is for, and the mechanics. The two that matter:

• Create only what is missing. Never move or rename an existing folder here — that breaks references. Restructuring an existing project is a task in its own right, not a setup step.
• Empty folders do not survive git. Mark each one with a .gitkeep. Files and folders starting with . are ignored by Unity's importer, so a .gitkeep needs no .meta and never appears in the project window — which makes it the only scaffold marker that does not create asset churn.

Show the user the tree you propose before creating any of it. A project with its own established layout keeps its own layout; adopt their names rather than imposing these.

7. Scan what is already there

Read references/first-run-scan.md and run it before writing STRUCTURE.md. A project adopting these skills has years of decisions in it; the scan reads them so the generated files describe the project rather than an ideal.

It is read-only — it changes nothing. Run the independent lookups as parallel read-only agents, and exclude third-party folders first or imported packages will dominate every ranking.

It produces three things: findings ordered by what hurts soonest, a backlog the user can hand straight to unity-manage-work, and the folder list STRUCTURE.md has to cover.

8. Write STRUCTURE.md

The structure file is the project's record of where things go, the thing CLAUDE.md points at when deciding where a new asset belongs, and the file unity-file-structure-habits checks the tree against. Generate it from the scan in Step 7 and what is actually on disk — never from the template — so it describes the project, including the folders that do not fit the scaffold.

Keep the folder list as a table, one row per folder, path first. That is the contract: it stays readable for a person and parseable for a drift check. Prose paragraphs describing the layout cannot be checked against anything.

Around the table: where scenes live and which are contested, the assembly definitions and what each covers, and the third-party folders that are off-limits.

Say in the file that it is expected to grow, that new categories are added as the project gains them rather than invented up front, and that a folder missing from the table is a gap in the table rather than a misplaced folder.

9. Write CLAUDE.md and AGENTS.md

Read references/project-memory.md for the content. In short, the generated CLAUDE.md carries:

• A one-paragraph description of the project, the editor version, and the path to the Unity project if it is not the repo root.
• The routing table — which skill covers which kind of work, so the right one fires without the user naming it.
• The task rule: when the user hands over a task, offer to run it through unity-manage-work before starting, and only proceed directly if they decline.
• The project's own hard rules: prefab-first, never hand-edit .unity/.prefab/.meta, every asset committed with its meta, and a pointer to STRUCTURE.md for where things go.
• How agents drive Unity: batch mode with the editor closed by default, the editor opened only on demand and closed again, and the user asked to test in the editor when work is done. Ask whether the user works on the same machine; if so, batch is the rule, not just the default.
• Who drives Unity (the agent doing the task, by default) and whether agents may save the open scene through the editor. Ask the user both; connected test runs in unity-scene-habits depend on the second.
• How agents work here, as pointers to the skills rather than copies: files first, with the compile check outside the editor once it is established; isolated tests while working, one full run at the end, and list, isolate, test, fix when it breaks; one writer at a time, with speed mode only on request; the preferred branch mode if the user has one (one session branch, or stacked branches per task); and the preferred autonomy mode (full automatic, semi automatic or human assisted). Without a preference, the manager asks both at kickoff.

AGENTS.md covers the same ground for tools that read that filename instead. Write it as a short file that points at CLAUDE.md rather than duplicating it — two copies of the same rules drift.

10. Verify and report

ls "$REPO/CLAUDE.md" "$REPO/AGENTS.md" "$REPO/STRUCTURE.md"
git -C "$REPO" status --short

Then prove batch mode works, with the editor closed: one batch builder or task method and one filtered EditMode test (unity-scene-habits, references/batch-mode.md). That also proves the licence works headless, which is the most common thing to find broken. Skip it if an editor has the project open, and say so. A project with no tests yet gets the builder run alone.

Then tell the user, in this order:

1. Anything broken that they must decide on, first: an ignored .meta, serialization not set to Force Text, UserSettings/ committed, a missing editor version, no licence.
2. What you created, and what you left alone because it already existed. Say whether the Pipeline package went in, was already there, or was skipped and why, and the same for ProBuilder, the batch mute script and the PlayMode test assembly. Report the batch smoke test and its timings.
3. The backlog from the scan — the real work the project needs, ordered, and the offer to run it through unity-manage-work.
4. That nothing is committed. Suggest it as its own commit — setup is not a feature change and should not ride along with one.

Never commit and never push from this skill.