New Unity Project

A guided flow from an idea to a running, version-controlled Unity project. This skill owns the flow — the questions, their ordering, running slow installs in the background while you ask, and the handoffs. It deliberately does not re-document commands; it delegates the mechanics to other skills.

Delegates to (read these for the actual commands — don't reinvent them):

unity-cli — CLI install, auth/license, Editor install, project creation, source control, opening the project. Its "Bootstrap a new project from scratch" workflow is the backbone here.
unity-package-management — installing packages via the C# PackageManager Client API, and choosing packages by genre / platform / monetization.
urp-postprocessing, ui, 2d-pixel-perfect — the visual baseline (Step 6): post-processing volume setup, HUD framework choice, pixel-perfect 2D.
implement-in-app-purchases, levelplay-unity-integration, build-live-game — monetization / backend integration (invoked at the end).

Work one step at a time. Ask only the current step's questions and wait for the user before moving on — platform and monetization answers change what you install, so don't gather everything up front or scaffold before they're settled.

The flow — and where the parallelism is

Concept — what they're building.
Platforms & monetization — then, as soon as platforms are known, kick off the Editor install in the background (it takes minutes) and keep talking.
(joins) Editor + platform modules finish installing.
Project + source control — create from a URP template matching 2D/3D; init git.
Packages — install via the C# Client API.
Visual baseline — post-processing, camera, quality tier, UI stack, pipeline-correct shaders, so the first frame doesn't look like an untouched template.
Save & first commit.
Hand off monetization / backend.

The whole point of a guided flow over a raw recipe: the multi-minute Editor install overlaps the minutes the user spends answering concept questions, so setup feels instant.

Step 1 — Concept

Use AskUserQuestion so the user can pick fast, but let them answer freely too. Cover:

Genre / core loop — platformer, top-down shooter, puzzle, idle, RPG, racing, card, tower defense, sim, hyper-casual, first-person, etc.
Dimension & look — 2D or 3D; art style (pixel, low-poly, stylized, realistic, UI-only).
Gameplay — the one-sentence "what the player does moment to moment."
Scope — single-screen prototype vs. multi-scene game; single-player or multiplayer.

Also settle on a project name. Write a 2–4 line project brief, read it back to confirm. The brief drives template choice (Step 4), packages (Step 5) and the visual baseline (Step 6): note the palette / mood words the user gives, and whether the look is pixel art.

Step 2 — Platforms & monetization, then start installing

Two decisions, because both change what you install:

Target platforms (multi-select): Desktop (Win/macOS/Linux), Mobile (iOS/Android), WebGL, Console. These map to Editor modules (Step 3) and argue for leaner packages on mobile/WebGL.
Monetization: none / premium / in-app purchases / ads / mix. This only decides which handoff skill you invoke in Step 8 — don't integrate it now.

Confirm the Editor version to use (default: latest LTS — see unity-cli for the LTS vs. Tech vs. beta trade-off). Ask this now, before kicking off the install, so you don't install the wrong one.

Then confirm prerequisites and launch the Editor install as a background task so it runs while you continue. See the unity-cli skill for exact syntax, module names per platform, and auth / license setup:

unity --version
unity auth status --format json      # if signed out:  unity auth login
unity license status --format json   # if none active: unity license activate

# Start in the BACKGROUND, then go straight back to the conversation. Module names per platform
# (android / ios / webgl / …) are in the unity-cli skill.
unity install lts --module <platform-modules> --yes --accept-eula

Run that install as a background task (don't block on it). If you have nothing left to ask, it's fine to just wait — the parallelism only helps when there's a conversation to overlap.

Step 3 — Join: Editor ready

Before creating the project, confirm the background install finished:

unity editors --installed --format json

If it failed, surface the error (see unity-cli troubleshooting) and stop — nothing downstream works without an Editor.

Step 4 — Create the project + source control

Follow the unity-cli "Bootstrap a new project from scratch" workflow verbatim:

List the real template ids the Editor offers (unity templates list --type core) and pick by render pipeline, not just 2D/3D — don't guess ids. Default to URP: com.unity.template.urp-blank ("Universal 3D") for 3D, com.unity.template.universal-2d ("Universal 2D") for 2D. com.unity.template.3d / com.unity.template.2d are the Built-in Render Pipeline templates — deprecated from Unity 6.5, removed in 6.7 — so choose them only when the user explicitly asks for Built-in. Confirm the pick against the JSON renderPipeline field (blank for universal-2d on current releases, so match that one by id).
Create with unity projects create "<Name>" --path <dir> --editor-version <v> --template <id>.
Set up source control — ask the user which they want, don't assume: Git (GitHub / GitLab; add --git-lfs for asset-heavy games) or Unity Version Control (--vcs uvcs, which handles large binary assets natively — no LFS), or a purely local git init + Unity .gitignore. Publish in one step with unity projects create --vcs … --git-token-stdin --no-initial-commit (tokens on stdin). Pass --no-initial-commit so the CLI doesn't commit the bare project before packages and .meta files exist — you make the real first commit/check-in in Step 7. See the unity-cli workflow for exact flags.

Step 5 — Packages

Map the brief to a concrete package list and install it via the unity-package-management skill (C# PackageManager Client API — never hand-edit manifest.json). Read that skill for the genre/platform/monetization → package mapping, the installer script, and the -quit gotcha. The template already provides the render pipeline — never add com.unity.render-pipelines.universal to a Built-in template project (nothing assigns a URP asset; materials go pink) or vice versa. Read the final list back to the user before installing; verify manifest.json afterward.

Step 6 — Visual baseline

A fresh template renders correctly but looks like a default: no tonemapping, untouched quality tier, flat colors. Left there, agents reach for OnGUI and guess shader names, which is where washed-out or magenta materials come from. Apply this floor before any gameplay work.

First, unity pipeline install --project-path "<project-path>", before opening the Editor. Running C# in the Editor, and unity command screenshot below, both need the project's com.unity.pipeline package. A project created in Step 4 does not have it, and Step 5 does not add it: that step installs packages by launching the Editor binary with -batchmode -executeMethod, which never touches the package. Installing before the open is the supported order — the install updates Packages/manifest.json, which Unity reads at project load. Run it against an already-open project and the CLI reports PIPELINE_MANIFEST_WRITE_FAILED; ask the user to close the Editor and re-run. Without the package, everything below fails to connect, which looks like the Safe Mode failure unity-cli describes but has a different cause.

Then unity open "<project-path>" (also what Step 7 needs), wait until unity status reports the Editor ready, and apply each item below by running C# in it. unity-cli owns those commands and their syntax — don't re-derive them here.

Items 1, 2, 5 and 6 assume a URP template, which is the Step 4 default. If the user explicitly chose Built-in, don't run them as written: UniversalAdditionalCameraData, Light2D, the urp-postprocessing volume framework and every Universal Render Pipeline/* shader are URP types that do not exist there, so the generated C# won't compile. On Built-in, items 3 and 4 still apply as written, post-processing means the legacy Post Processing Stack, and the shader names are Standard / Unlit/Color. Don't reach for migrate-birp-to-urp — the user asked for Built-in.

Post-processing. Global Volume with Tonemapping (ACES), low Bloom (intensity 0.5–1, threshold 0.9) and a subtle Vignette (≈ 0.25); set renderPostProcessing = true on the main camera's UniversalAdditionalCameraData. REQUIRED SUB-SKILL: urp-postprocessing — its code templates create the volume and check HDR and the Volume layer mask.
Camera and light. 2D → orthographic, solid background color from the brief's palette, and a Light2D of type Global in the scene if the template scene has none (the Sprite-Lit shaders render black without one). 3D → perspective; keep the template's directional light and skybox, main-light shadows on.
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.
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.
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.
Pixel art only. Point filter mode on sprites and a Pixel Perfect Camera — see 2d-pixel-perfect.

Save the scene, then confirm both of these. Not with unity logs — that reads the CLI's own log, never the Editor's, so it 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 screenshot --output baseline.png looks lit and tonemapped rather than flat gray.

Step 7 — Save & first commit

The project is already open from Step 6, so .meta files exist. Make the first commit with whichever VCS you set up in Step 4:

unity open "<project-path>"     # only if not already open; for headless/CI use the
                                # "Import & save headlessly" method in unity-package-management

Git (GitHub / GitLab / local):

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 must be committed together with its .meta.

Unity Version Control (UVCS): check in through your UVCS client/workspace (created during Step 4) — there's no git step. Generated folders are still excluded by the ignore rules.

If you published via --vcs in Step 4 without --no-initial-commit, the CLI already made an initial commit of the bare project — add a follow-up commit here rather than double-committing.

Step 8 — 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

Report the project path, Editor version, render pipeline and template, installed packages, the visual baseline applied, and next steps.

Scope — what this skill does NOT do

No gameplay scaffolding. It gets you to a running, wired project with a visual floor; building the actual game (scenes, controllers, art) is the next conversation — iterate there with the Editor via the unity-cli MCP server and the Package Manager. Generic genre skeletons tend to produce throwaway mocked primitives, so this skill intentionally stops at a clean starting point. The visual baseline (Step 6) is settings, not content.
No command reference. Syntax lives in unity-cli / unity-package-management.

Checklist

Concept brief captured and confirmed (genre, look, gameplay, scope, name)
Platforms + monetization recorded; Editor version chosen
Editor + platform modules installed (started in the background during Step 2)
Project created from a URP template (urp-blank / universal-2d) unless Built-in was explicitly requested; git initialized with a Unity .gitignore
Packages installed via the C# Client API; manifest.json verified; no render-pipeline package added on top of the template
Visual baseline applied: global Volume (tonemapping, bloom, vignette) + camera post-processing on, quality tier set for the target, UI stack chosen (no OnGUI), URP shader names, screenshot checked
Project opened/saved so .meta files exist; first commit made; Library/ excluded
Handed off to the monetization/backend skill if applicable

Common mistakes

Blocking on the Editor install instead of backgrounding it while you ask questions.
Installing the wrong Editor because the version wasn't confirmed before the background install.
Gathering all questions up front — platform/monetization answers change the modules and packages.
Hand-editing manifest.json instead of using the Client API (see unity-package-management).
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 because the name matches — those are the Built-in pipeline templates. Use universal-2d / urp-blank.
Skipping the visual baseline and shipping the template's flat defaults, then building the HUD with OnGUI and materials with Shader.Find("Standard") under URP.

new-unity-project