Pmndrs Xr
Developmentpmndrs-xrPmndrs Xr is an Agent Skill for development published in the pmndrs/xr repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Build, modify, debug, or validate XR, AR, VR, spatial interaction, pointer, controller, hand-tracking, hit-test, teleportation, layer, anchor, uikit, and handle-based React Three Fiber apps using @react-three/xr, @react-three/handle, and @react-three/uikit. Use when working on immersive WebXR experiences, R3F-to-XR conversions, XR games, spatial tools, or XR validation/test harnesses.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/pmndrs/xr/blob/HEAD/skills/pmndrs-xr/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/pmndrs-xr, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
PMNDRS XR
Use this skill for WebXR experiences built with React Three Fiber and the React Three XR/uikit/handle packages.
Core Workflow
- Inspect the app structure and package manager before editing.
- If the workspace is empty, scaffold a minimal runnable vertical slice first: package scripts,
src/main,src/App, styles, andvitexec/play. Get that slice building before expanding the scene. - Use the React Three Fiber architecture:
@react-three/xrplus<Canvas>and<XR store={store}>. - Enter AR/VR from a real user gesture such as a DOM button calling
store.enterAR()orstore.enterVR(). - Put immersive status, score, checklist, report, and controls inside the 3D/WebXR scene. DOM is acceptable for the initial session-entry button and optional desktop fallback, not as headset UI.
- Build interactions through real spatial input: pointer events when appropriate, documented handle components, controller/hand pose, near interaction, controller select events, hit-test, or anchors.
- For editor/configurator/assembly tasks, use visible handles/gizmos or grabbable affordances and prove drag/translate/rotate/snap behavior through object transform changes.
- Validate with a live XR walkthrough when the task is an XR experience. The passing path should enter an emulated XR session, move the headset/viewer, aim controllers, interact with visible in-scene targets, record video, and assert view composition.
Reference Routing
Read the smallest relevant reference first:
- Architecture and package choice: references/architecture.md
- In-scene UI and visual quality: references/ui-and-visual-quality.md
- Domain fit for games, training, simulation, commerce, and tools: references/use-case-patterns.md
- Spatial interaction patterns: references/interactions.md
- XR validation with vitexec/IWER: references/validation.md
- Dependency/version pitfalls: references/dependencies.md
Generated upstream docs are also bundled:
- Getting started:
references/docs/getting-started/introduction.md - Store/session options:
references/docs/tutorials/store.md - Interactions:
references/docs/tutorials/interactions.md - Origin/teleport:
references/docs/tutorials/origin.md,references/docs/tutorials/teleport.md - AR features:
references/docs/tutorials/anchors.md,dom-overlay.md,hit-test.md,object-detection.md - Handles:
references/docs/handles/introduction.md - Full index:
references/index.md
If unsure which page applies, search references:
rg -n "createXRStore|TeleportTarget|XRHitTest|pointerEventsType|XROrigin|DefaultXRController|Handle|uikit" path/to/skill/references
Quality Bar
- Build the actual experience as the first screen, not a landing page.
- For complex XR apps, avoid long up-front design or broad
node_modulesarchaeology. Read only the specific bundled reference needed for the immediate API choice, then implement and validate the smallest real path before adding polish. - Avoid placeholder-cube demos. Use domain-specific environment context, recognizable objects, lighting/material variation, spatial affordances, and visible feedback.
- Keep desktop fallback useful, but do not let it become the proof for XR behavior.
- Do not weaken validation to pass. If controller input misses, fix target geometry, ray pose, readiness, occlusion, or event handling.
- Use patch/file-edit operations for generated JSX/TS/HTML/vitexec files. Do not use shell heredocs for code files.
Before Finishing
Confirm the result has:
createXRStoreand user-facing session entry.<XR store={store}>around scene content.- In-scene XR UI for immersive status/score/report/controls.
- Real pointer/controller/handle/hit-test interaction, not validation-only state mutation.
- For manipulation tasks, before/after transform assertions for dragged, grabbed, rotated, scaled, or snapped objects.
- A build plus browser/XR validation covering the main path.
- Recording or screenshots plus logs proving active XR, controller input, viewer movement, and readable target composition.