agentleFS
mirzaaghazadehmirzaaghazadeh/iwsdk-webxr-skills/skills/custom/iwsdk-project-setup/SKILL.md

iwsdk-project-setup

Skill1 starsChanged 30 days agoMITView on GitHub

Sets up a machine and a project for Meta Immersive Web SDK (IWSDK) WebXR development with Claude Code: checks Node, maps the game pitch to `npm create @iwsdk@latest` flags (vr/ar/browser, physics, locomotion, grabbing, scene understanding), explains the generated files (AGENTS.md, .claude skills/rules/agent), connects Claude Code to the iwsdk-runtime (55 tools), iwsdk-reference and metavr MCP servers with `adapter sync`, starts the CLI-managed dev server (HTTPS, port 8081, IWER incl. `metaVRGlasses`, agent or collaborate mode), and fixes headless/cloud setups (IWSDK_GPU, Playwright Chromium). Use when starting an IWSDK or WebXR project, when the user says "set up IWSDK", "npm create @iwsdk", "scaffold a WebXR game", "MCP tools missing", "which MCP tools exist", "iwsdk-runtime not connected", "Node version unsupported", "port 8081 in use", "Executable doesn't exist" (Playwright), "EALLOWSCRIPTS" in the scaffold's install, when cloning a teammate's IWSDK repo, or when adding IWSDK to an existing Vite app.

  • Deletes or force-pushes
  • Installs packages

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 1 is distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Never run npm i -g or edit ~/.claude without a yes.

    line 41
  2. Very specific:

    Don't install duplicate skills: Every scaffold already contains the 12 official skills in .claude/skills/ (and a copy in .agents/skills/).

    line 44
  3. Very specific:

    Always use the scoped name npx @iwsdk/cli ...

    line 47
  4. Very specific:

    Check flags with --help before relying on them: npx @iwsdk/create@latest --help, npx @iwsdk/cli dev up --help.

    line 49
  5. Very specific:

    Every boolean also has a --no-… form.

    line 86
  6. Distinctive:

    If the pitch is ambiguous in a way that changes the target or a feature, ask.

    line 89
  7. Very specific:

    If MCP tools are missing or deferred, use the CLI: every tool has a CLI twin (xr_get_session_status = npx @iwsdk/cli xr status, …

    line 149
  8. Very specific:

    Wait for browserCommandReady: true before browser, XR or ECS commands.

    line 169
  9. Very specific:

    Prefer scaffolding a throwaway project with the same target and copying its iwsdk.config.json, vite.config.ts, src/assets.ts, …

    line 209
  10. Very specific:

    Telemetry: when it is installed, @iwsdk/cli and the Vite plugin report each runtime tool call (tool name, duration, a fixed failure code, …

    line 234

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

IWSDK project setup

Made by Navid Mirzaaghazadeh · part of iwsdk-webxr-skills · MIT

Gets a machine and a project to the state the official iwsdk-* skills expect: an IWSDK 1.x manifest-first project, dependencies installed, Claude Code connected to the project's MCP servers, and npx @iwsdk/cli dev status reporting browserCommandReady: true.

Hand-offs: building features → iwsdk-dev; testing on a Quest → iwsdk-quest-device-testing; 0.4.x projects (GLXF, Meta Spatial Editor) → iwsdk-migrate-0-5 first.

Ground rules

  • Ask before installing Node, Playwright browsers, Android platform tools, or anything global. Never run npm i -g or edit ~/.claude without a yes.
  • adapter sync writes project config (.mcp.json, .claude/settings.json). Say so before running it in an existing repo.
  • Don't install duplicate skills. Every scaffold already contains the 12 official skills in .claude/skills/ (and a copy in .agents/skills/). Install only this library's custom/ and extra skills into such a project.
  • Always use the scoped name npx @iwsdk/cli ... (never an unscoped iwsdk package via npx). The scope is a security boundary: npx could fetch an unrelated package otherwise.
  • Check flags with --help before relying on them: npx @iwsdk/create@latest --help, npx @iwsdk/cli dev up --help. This skill was checked against 1.0.1 (npm latest; 1.1.0-rc.1 sits on next and moves three to super-three@0.185.0: use it only if the user asks).
  • IWSDK's docs on Meta's site (https://developers.meta.com/vr/documentation/iwsdk/guides/overview/) were generated from IWSDK 0.5.3. They show unscoped npx iwsdk …, port 5173, 45 MCP tools and two VR Glasses config keys 1.0.1 rejects. Prefer the installed package and https://iwsdk.dev; differences: docs/meta-reference/web-iwsdk-docs-on-meta.md.

1. Check the machine

node --version      # must satisfy >=20.19.0 <21 || >=22.12.0 <23 || >=24.0.0
npm --version
git --version

The engine range comes from every @iwsdk/* package.json; the scaffold's .nvmrc is 22.12.0. Node 18 and Node 21/23 are rejected by @iwsdk/cli. If Node is wrong, ask which version manager the user has (nvm, fnm, Volta, Homebrew) and use it; don't pick one for them.

Optional now, needed for the headset: Android platform tools (adb version) and desktop Chrome (for chrome://inspect). See iwsdk-quest-device-testing.

2. Turn the pitch into flags

Pitch saysFlag
Fully virtual world--target vr
Passthrough, content in the real room--target ar (the session mode is immersive-ar)
Desktop browser 3D, no headset--target browser
Gravity, collisions, throwing--physics (Havok; adds a JS + WASM payload)
Walk/teleport through a big space--locomotion (VR and browser only)
Pick up and move objects--grabbing
Real walls, floors, tables, anchors--scene-understanding (AR only)
Place things on real surfaces (hit test)--environment-raycast (AR only)

Every boolean also has a --no-… form. Defaults with --yes: TypeScript, git init, install. Recommended baselines (create README): VR = locomotion on a worker + grabbing, no physics; mixed reality = grabbing only; desktop = browser camera, input, locomotion, interactions. If the pitch is ambiguous in a way that changes the target or a feature, ask.

3. Scaffold

# new folder (npm create needs `--` before flags)
npm create @iwsdk@latest my-game -- --yes --target vr --grabbing --physics --no-locomotion

# same thing via npx
npx @iwsdk/create@latest my-game --yes --target vr --grabbing --physics --no-locomotion

# inside an existing, non-empty repo: --force is required and overwrites conflicting generated files
npx @iwsdk/create@latest . --yes --force --target vr

Useful extras: --no-install (inspect first), --no-git, --language js, --skip-reference-warmup (skip the reference model download). Confirm before --force: it overwrites generated files, keeps unrelated files and the existing git repo.

What lands in the project (full table: references/generated-files.md):

iwsdk.config.json       project authority: scene, asset/component modules, world.xr, features, dev.emulator
src/index.ts            World.create(container, projectOptions from 'virtual:iwsdk-project') + registerSystem
src/assets.ts           defineAssets({...}): the asset catalog shared by runtime and editor
src/components.ts       defineComponents([...])
public/scenes/main.iwsdk.scene.json   authored scene (iwsdk.scene.v1)
public/ui/welcome.uikitml             spatial UI panel
AGENTS.md + CLAUDE.md   CLAUDE.md is "@AGENTS.md"
.claude/                skills (12), rules (4), agents/iwsdk-project-code-reviewer.md, settings.json

Change features in iwsdk.config.json (world.features, world.xr.features), not by re-scaffolding. Editing it restarts Vite in place.

4. Install and connect Claude Code

cd my-game
npm install                                   # skip if create already installed
npx @iwsdk/cli adapter sync --tools claude    # create runs `adapter sync` (all tools) after installing
npx @iwsdk/cli adapter status
npx @iwsdk/cli reference warmup               # one-time download of the reference corpus + pinned model
npx @iwsdk/cli reference status

adapter sync --tools claude writes .mcp.json with up to three stdio servers, each run with node and an absolute path into node_modules:

ServerRunsGives Claude
iwsdk-runtime@iwsdk/cli/dist/cli.js mcp stdio55 tools in 1.0.1: xr_* (16), browser_* (6), scene_* (13, incl. 3 live-runtime inspectors), ecs_* (11), ui_* (3), asset_render_preview, runtime_* (5, session and headset pairing). Meta's pages say 45 (0.5.3) or 32; trust npx @iwsdk/cli mcp inspect
iwsdk-reference@iwsdk/reference entrypointsemantic search, API lookup, component/system lists
metavr@meta-quest/metavr/bin.js mcp serverQuest device control, Meta docs search, 3D asset search

It also adds enabledMcpjsonServers and narrow mcp__<server>__* allow rules to .claude/settings.json, and removes an old enableAllProjectMcpServers: true if present. Then restart the Claude Code session and check with /mcp. Snippet and details: references/claude-code-mcp.md.

If MCP tools are missing or deferred, use the CLI: every tool has a CLI twin (xr_get_session_status = npx @iwsdk/cli xr status, browser_screenshot = npx @iwsdk/cli browser screenshot). npx @iwsdk/cli mcp inspect --tool <name> prints a schema.

Cloned a teammate's repo? .mcp.json, .cursor/mcp.json, .vscode/mcp.json, .codex/config.toml and .iwsdk/ are git-ignored by the scaffold. Run npm install, then npx @iwsdk/cli adapter sync --tools claude and reference warmup on each machine.

5. Start the dev server

npm run dev                                   # = iwsdk dev restart --open --foreground (headed, attached)
npx @iwsdk/cli dev up --ai-mode agent         # headless, fixed 800x800 viewport, returns to the shell
npx @iwsdk/cli dev up --ai-mode collaborate   # one visible managed Chromium window with Runtime/Editor
npx @iwsdk/cli dev status                     # data.runtimeUrls.local / .network, data.state.browserCommandReady
npx @iwsdk/cli dev logs --tail 100
npx @iwsdk/cli dev down
  • The developer owns headed vs headless. Announce a change before restarting.
  • Wait for browserCommandReady: true before browser, XR or ECS commands; dev up can return earlier. (Meta's AI page also names state.session.browser.commandReady; in 1.0.1 browserCommandReady is computed from it.)
  • Port 8081 (vite.config.ts server.port) fails if busy instead of moving. Stop the other process (lsof -i :8081) or change the port.
  • HTTPS is on: iwsdkDev() generates a self-signed certificate cached in .iwsdk/https and installs no CA. The managed browser accepts it; a headset shows a one-time warning. iwsdkDev({ https: false }) opts out (WebXR then only works on localhost).
  • First smoke test: npx @iwsdk/cli browser screenshot --output-file artifacts/first.png, then npx @iwsdk/cli xr enter and npx @iwsdk/cli xr status.

6. Emulator (IWER) settings

In iwsdk.config.json → dev.emulator (defaults from @iwsdk/vite-plugin-dev types):

KeyDefaultNotes
devicemetaQuest3also metaQuest2, metaQuestPro, metaVRGlasses, oculusQuest1. metaVRGlasses (IWSDK 1.0.0+, IWER 2.5.0+) = Quest 3 capabilities plus the glasses' view mask (74° × 68°: 25° up, 43° down) and a gaze source; pick Gaze + Hands in the toolbar (iwsdk-vr-glasses)
activationlocalhostemulate only on localhost; always or a RegExp
userAgentException/OculusBrowser/never emulate in Quest Browser
environmentnone (AR scaffolds use living_room)living_room, meeting_room, music_room, office_large, office_small. 1.1.0-rc.1 replaces them with sunlit_living_room, home_office, conference_room, open_office, kitchen, bedroom, music_studio, open_studio (old ids still load, mapped)
iwertruefalse = never inject (browser-only apps)
injectOnBuildfalsekeep false for store builds

Next to it, dev.targetDevicePreview.gazeSimulation: "head" (1.0.1) adds a head-directed test gaze source to a real Quest session when the app requests gazeTracking; dev server only, and it needs iwer left on (iwsdk-quest-device-testing §7).

7. Cloud and headless machines

  • The managed browser is Playwright Chromium. It picks GPU or SwiftShader automatically; override with IWSDK_GPU=auto|gpu|swiftshader (vite-plugin-dev/src/managed-browser/launch.ts). SwiftShader frame times are meaningless for performance.
  • Executable doesn't exist at …/chromium_headless_shell-…: install the browser for the Playwright version the project resolves: npm ls playwright, then npx playwright@<that version> install chromium (on Linux CI add --with-deps).
  • Long screenshots cost context: --screenshot-width 500 --screenshot-height 500 on dev up.

8. Adding IWSDK to an existing Vite app

Prefer scaffolding a throwaway project with the same target and copying its iwsdk.config.json, vite.config.ts, src/assets.ts, src/components.ts, .claude/ and AGENTS.md. The runtime needs one shared Three.js instance:

{
  "dependencies": { "@iwsdk/core": "^1.0.1", "three": "npm:super-three@0.181.0" },
  "overrides": { "three": "npm:super-three@0.181.0" }
}

(pnpm reads the override from pnpm-workspace.yaml.) Import Three.js classes from @iwsdk/core, not three. Keep every @iwsdk/* package on the same version.

9. Side effects and privacy

Scaffolds add @meta-quest/metavr (Meta's Quest CLI) as a dev dependency. Tell the user, before the first npm install, what it does:

  • Postinstall writes outside the project (read in postinstall.js / download.js of 1.8.1): it downloads the metavr binary from securecdn.oculus.com into ~/.metavr (or $METAVR_HOME) and appends a completions block to ~/.zshrc, or ~/.bash_profile / ~/.bashrc, or the PowerShell profile. To avoid that, install with METAVR_SKIP_DOWNLOAD=1 npm install (the binary is then fetched on first metavr run), or remove the package.
  • Telemetry: when it is installed, @iwsdk/cli and the Vite plugin report each runtime tool call (tool name, duration, a fixed failure code, session id) through metavr, which also has its own telemetry. npm exec metavr -- telemetry status / telemetry disable (essential only).
  • npm uninstall @meta-quest/metavr stops both, and removes the metavr MCP server and device tools (you can still use adb directly). Let the user choose.

Troubleshooting

SymptomFix
Unsupported Node from @iwsdk/cliNode outside the engine range (step 1)
dev up fails, port in useanother server on 8081; stop it or change server.port
browser_not_launchedstarted with --no-open; npx @iwsdk/cli dev restart --open
Runtime commands time outxr status → browser logs → browser reload → dev restart, in that order
iwsdk-runtime tools absent in Claudeadapter sync --tools claude, restart session, /mcp; use CLI meanwhile
Reference tools say warmup requirednpx @iwsdk/cli reference warmup
Cryptic errors from node_modules/.vite/deps/chunk-*.js after an updatestop the server, rm -rf node_modules/.vite/deps, start again (IWSDK troubleshooting page)
"Only pmndrs/uikit components can be added as children"duplicate Three/UIKit graph; keep the scaffold's resolve.dedupe in vite.config.ts
Scaffold's install step fails with EALLOWSCRIPTS (--allow-scripts not allowed in project installs), seen with npm 11.19The project is created; install by hand: npm install, then npm install-scripts approve esbuild protobufjs and npm install-scripts deny @meta-quest/metavr onnxruntime-node (the intent of the scaffold's pnpm settings). Denying metavr's script also skips its ~/.metavr download and shell-profile edit (§9)
Two IWSDK apps on one machineBoth scaffolds use 8081 and the port is strict; give the second app another server.port (and use that port on the headset)
/mcp shows two or three metavr servers, and every hz-* skill twiceSomeone ran metavr init, which installs Meta's plugin, skills and an MCP entry at user scope (metavr 1.8.0.17.10, 2026-10-25). Keep adapter sync's entry and one source of skills; this library's docs/meta-reference/ai-tools.md §3 lists what metavr init writes and how to move it into the project

Sources

Last verified: 2026-10-25 (the metavr init row); 2026-10-17 (the rest)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.