meta-vr

Meta VR Agentic Tools

Agentic skills and tools for Meta VR and Horizon OS development.

What is this?

This repository packages a curated set of agentic tools and skills for Meta VR and Horizon OS development, along with shared metavr references and contribution/process documentation for maintaining the skill ecosystem.

The skills follow the open Agent Skills model: each skill has a required SKILL.md plus optional supporting files that are loaded on demand. This repo includes packaging artifacts for Claude Code, Cursor, Codex, GitHub Copilot CLI, and Gemini-compatible environments.

Skills are powered by the metavr (Meta VR CLI), which provides device management, app management, performance tooling, and documentation search through both direct commands and an MCP server.

Prerequisites

• metavr CLI: install it natively or invoke via npx with no install (see Install the metavr CLI)
• Meta VR device with Developer Mode enabled (for on-device skills)

Install the metavr CLI

Standalone binary

Install the standalone binary on your PATH (no prerequisites):

# macOS and Linux
curl -fsSL https://developers.meta.com/horizon/install-cli/ | sh

# Windows (PowerShell)
iwr -useb https://developers.meta.com/horizon/install-cli/windows/ | iex

The installer adds metavr to your PATH (source your shell rc or open a new terminal to pick it up). If you installed the standalone binary, keep it current with metavr update.

npm distribution

The npm distribution requires Node.js 16 or newer, and needs no install of its own:

npx -y metavr --version

With Bun, substitute bunx metavr for npx -y metavr (no -y needed).

Commands in this README use the bare metavr form. If you use the npm distribution, prefix with npx -y.

Installation

Muse Code

The fastest path on any agent is metavr init: it detects your installed agents and sets up these skills plus the metavr MCP server (Muse Code is configured first):

metavr init

Prefer the plugin route instead:

muse plugins marketplace add meta-vr meta-quest/agentic-tools
muse plugins install meta-vr@meta-vr

Claude Code

Add Meta VR Agentic Tools marketplace and install the agentic tools plugin

Within claude run:

/plugin marketplace add meta-quest/agentic-tools
/plugin install meta-vr@meta-vr

Cursor

Install from the Cursor marketplace with:

/add-plugin meta-quest-agentic-tools

Or install online at: https://cursor.com/marketplace/meta-reality-labs

Codex

codex plugin marketplace add meta-quest/agentic-tools
codex plugin add meta-vr

GitHub Copilot CLI

copilot plugin marketplace add meta-quest/agentic-tools
copilot plugin install meta-vr@meta-quest

Gemini

gemini extensions install https://github.com/meta-quest/agentic-tools

Install with a skills CLI

Direct install

These editor-agnostic CLIs install the skills from this repo into whichever agent you choose, independent of any editor or plugin marketplace.

Agent Skills CLI (gh skill)

Published as Agent Skills releases and installable with the built-in gh skill command. Requires a recent GitHub CLI (gh) — gh skill is a preview feature.

# Install all skills from this repo
gh skill install meta-quest/agentic-tools

# Install a single skill
gh skill install meta-quest/agentic-tools hz-spatial-sdk

# Target a specific agent, or install for all projects
gh skill install meta-quest/agentic-tools --agent claude-code --scope user

skills.sh (npx skills)

# Add every skill from this repo
npx skills add meta-quest/agentic-tools

Browse the catalog at skills.sh/meta-quest/agentic-tools.

Context7 (npx ctx7)

# Interactive — pick from a list
npx ctx7@latest skills install /meta-quest/agentic-tools

# Install a specific skill, or everything
npx ctx7@latest skills install /meta-quest/agentic-tools hz-spatial-sdk
npx ctx7@latest skills install /meta-quest/agentic-tools --all

# Target a specific IDE: --claude, --cursor, --universal (.agents/skills/), or --global
npx ctx7@latest skills install /meta-quest/agentic-tools --all --claude

MCP Server

metavr includes a built-in Model Context Protocol (MCP) server with 40+ tools for device management, app control, file operations, documentation search, performance tracing, and more. This lets AI coding assistants interact directly with your Meta VR device.

Install the MCP server into your AI tool

If you use the npm distribution instead of the standalone binary, prefix every command below with npx -y (or bunx for Bun users; no -y needed).

# Muse Code
metavr mcp install muse-code

# Claude Code
metavr mcp install claude-code

# Claude Desktop
metavr mcp install claude-desktop

# Cursor
metavr mcp install cursor

# VS Code / VS Code Insiders
metavr mcp install vscode
metavr mcp install vscode-insiders

# Windsurf
metavr mcp install windsurf

# Zed
metavr mcp install zed

# Android Studio (Gemini)
metavr mcp install android-studio

# Gemini CLI
metavr mcp install gemini-cli

# OpenAI Codex CLI
metavr mcp install codex

# LM Studio
metavr mcp install lm-studio

# OpenCode
metavr mcp install open-code

# Google Antigravity (Gemini)
metavr mcp install antigravity

# Generic project-local config
metavr mcp install project

Or start the MCP server directly:

metavr mcp server

Skills

Skill	Description
metavr-cli	Provides the complete metavr (Meta VR CLI) reference for Meta VR and Horizon OS development — installation, device setup, command discovery, MCP server mode, documentation search, app deployment, device testing setup, audio control, screenshots, and performance analysis. Use when the user needs to install metavr, asks what commands are available, needs CLI syntax help, or wants to know what metavr can do. Build paths: all Meta VR app stacks; use hz-quest-verify-first if the build path is unclear.
hz-android-2d-porting	Guides porting existing Android 2D apps to Meta VR and Horizon OS — input adaptation, panel layout, and design requirements. Use when adapting a mobile Android app for Meta VR. For UI design decisions, use hz-panel-designer if available. Build path: Standard Android; use hz-quest-verify-first if the build path is unclear.
hz-api-upgrade	Upgrades Meta VR apps to newer Horizon OS SDK versions — migration guides, deprecated API replacements, changelog. Use when updating SDK versions or fixing deprecated API warnings. Build paths: all Meta VR app stacks; use hz-quest-verify-first if the build path is unclear.
hz-unity-sdk-upgrade	Upgrades Unity projects between Meta XR SDK versions for Meta VR and Horizon OS. Use when moving from Oculus Integration or older com.meta.xr packages, resolving post-upgrade compile errors, or validating runtime behavior. Grounds migration decisions in current metavr documentation results and records coverage gaps instead of relying on static summaries. Do not use for Unreal, native Android, Spatial SDK, or WebXR upgrades.
hz-immersive-designer	Guides design of comfortable, intuitive VR/MR experiences for Meta VR and Horizon OS — comfort guidelines, interaction patterns, spatial layout, accessibility. Use during UX design review or when evaluating comfort and accessibility. Build paths: Meta Spatial SDK, Unity, Unreal, native OpenXR, and WebXR; for 2D panel apps use hz-panel-designer if available. Use hz-quest-verify-first if the build path is unclear.
hz-iwsdk-webxr	Builds WebXR experiences for Meta VR and Horizon OS using the Immersive Web SDK (IWSDK) — ECS architecture, Three.js integration, spatial UI. Use when creating web-based VR/MR apps for Quest Browser.
hz-metavrx-layout-sdk	Build multi-window Meta Horizon OS experiences with the MetaVrx Layout SDK in Jetpack Compose or React Native. Covers framework selection, setup, anchoring, semantic offsets, window promotion, fallback, priority, lifecycle, and theming. Use for apps that need multiple app-owned panels without an immersive scene. Build path: Standard Android, including React Native; use hz-quest-verify-first if the path is unclear, and do not use this skill for immersive Spatial SDK scenes.
hz-metavrx-ui-set	Builds app UI for Meta VR and Horizon OS with the MetaVrx UI Set, a Jetpack Compose component library and design system. Covers UiSetTheme, buttons, cards, controls, dialogs, dropdowns, inputs, side navigation, sliders, tooltips, the Icons.Regular library, Gradle setup, and migration from the Spatial SDK UI Set. Build path: Standard Android; use hz-quest-verify-first if the path is unclear.
hz-new-project-creation	Scaffolds new Meta VR and Horizon OS projects after the build path is selected — Standard Android, Meta Spatial SDK, Unity, Unreal, or WebXR. Use when creating a new Meta VR app from scratch. Build paths: all; use hz-quest-verify-first to choose the path.
hz-perfetto-debug	Analyzes Meta VR and Horizon OS VR performance using Perfetto traces — frame timing, CPU/GPU bottlenecks, render pass analysis. Use when profiling frame drops, jank, or thermal issues on Meta VR devices. Build paths: all Meta VR app stacks; use hz-quest-verify-first if the build path is unclear.
hz-platform-sdk	Guides integration of the Horizon Platform SDK for Meta VR and Horizon OS Android/Kotlin apps — achievements, IAP, users, leaderboards, presence, notifications, abuse reporting, entitlements, asset files, application lifecycle, consent, device integrity, language packs, user age categories, and rate and review. Covers setup, initialization, API usage, data types, error handling, and best practices for all 17 public platform SDK packages. Build paths: Standard Android and Meta Spatial SDK; use hz-psdk-integration for guided integration, hz-unity-platform-sdk for Unity/C#, and hz-quest-verify-first if the path is unclear.
hz-psdk-integration	Guides interactive Horizon Platform SDK (PSDK) integration for Meta VR and Horizon OS Android/Kotlin apps — analyzes the codebase, recommends public platform features, plans the integration, and validates on device. Use for workflow guidance; use hz-platform-sdk for the detailed API reference. Build paths: Standard Android and Meta Spatial SDK; use hz-quest-verify-first if the path is unclear.
hz-quest-verify-first	MANDATORY pre-flight check before answering any question or writing any code related to Meta Quest VR headsets (Quest 2, Quest 3, Quest 3S, Quest Pro) or apps that target them. Forces verification against authoritative Meta sources via the metavr CLI / metavr MCP tools BEFORE relying on training-data knowledge. Counters the failure mode where agents answer Quest-related questions from stale memory and ship deprecated APIs, broken Android manifests, and store-rejected builds. Loads automatically when the user is in a Quest project (any reference to Oculus / Meta Quest / Horizon OS, Unity OVR or Meta XR packages, com.meta.* / com.oculus.* package IDs, Quest-targeted AndroidManifest, .meta files, or developers.meta.com / developer.oculus.com URLs). Build paths: all; use this skill first whenever the path is unknown or a Quest-specific claim is involved.