Agent Guide — Meta VR Agentic Tools

This file helps AI agents navigate and use this repository effectively.

What this repo is

A skills repository for AI coding agents that provides domain-specific guidance for Meta VR and Horizon OS development. Skills are not code libraries — they are structured prompts and reference documentation that teach agents how to perform Meta VR development tasks. The repo includes Claude Code, Cursor, Codex, GitHub Copilot CLI, and Gemini-compatible packaging, and the skill format is intended to remain compatible with the broader open Agent Skills ecosystem.

How skills work

Each skill is a directory under skills/ with:

• SKILL.md — required; the main skill definition and prompt
• optional supporting files/directories such as references/, scripts/, assets/, examples/, and agents/

Agents should read SKILL.md first, then selectively load only the supporting files needed for the current task. Do not assume every skill has a references/ directory, and avoid loading all supporting files upfront.

Shared references

The current repo keeps general metavr reference material in:

• docs/metavr-cli.md for the generated end-to-end CLI reference
• skills/metavr-cli/ for install guidance, MCP usage, and focused metavr deep dives

When a skill needs generic metavr command guidance, prefer referencing those existing docs instead of creating another parallel copy.

Skill index

Key tool: metavr

metavr is the primary action layer for the device-interacting skills in this repo. It runs as an MCP server or directly via command line.

# MCP server mode (for agent integration)
metavr mcp server

# Direct CLI
metavr device list
metavr app install ./app.apk
metavr perf capture
metavr docs search "hand tracking"

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

metavr installs these skills, so the GitHub release is a contract

metavr skills install reads this repo's published GitHub release: it takes releases/latest, resolves the tag to a commit, and installs skills/* from that commit's tarball into the user's ~/.agents/skills.

Two things follow for anyone publishing here:

• A tag must never move. metavr records the commit each tag resolved to and refuses to update when the same tag later points somewhere else, because a moved tag is indistinguishable from a compromise. Re-cutting a release breaks installed clients on purpose — publish a new version instead. Enabling GitHub immutable releases and tag protection would make this impossible rather than merely detected.
• An unpushed export ships nothing. metavr installs from github.com, not from __github__/, so a landed export that has not been pushed and tagged is invisible to every user.

Each skill is validated on the way in: SKILL.md must parse, and its frontmatter name must equal its directory name. One invalid skill fails the whole bundle, so a malformed skill blocks the release for all of them rather than shipping partially.

Deprecating or removing a skill is unaffected by any of that. Tag immutability constrains republishing an already-published version, not what the next version contains. To retire a skill: delete it here (or drop it from fb_only/fb-policy-allowlist.json to keep it internal-only), re-export, and cut a normal release. On the next metavr skills update, a user who has it installed gets it removed — but only if it is still byte-identical to what metavr wrote. A copy the user edited is kept and reported as no longer published, so retiring a skill upstream never silently deletes someone's local work. metavr skills update --check lists the pending removals before anything is touched.

Deprecating in place (keeping the directory but marking it dead) is not a thing metavr can act on: the fb-only.deprecated flag is stripped by the exporter, so it never reaches the published bundle the client reads. If we want a soft-deprecation signal for users rather than a removal, it has to move out of fb-only into public frontmatter first.

Directory structure

.
├── .plugin/                 # Vendor-neutral Open Plugins manifest + marketplace
├── .claude-plugin/          # Claude Code plugin metadata
├── .cursor-plugin/          # Cursor plugin manifest
├── .codex-plugin/           # Codex plugin manifest
├── .agents/plugins/         # Codex / Open Plugins repo marketplace
├── .github/plugin/          # GitHub Copilot CLI plugin metadata
├── .mcp.json                # Shared MCP server configuration
├── docs/                    # Generated metavr CLI reference
├── gemini-extension.json    # Gemini extension manifest
├── skills/
│   └── ...
├── AGENTS.md                # This file
├── CLAUDE.md                # Symlink → AGENTS.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── SECURITY.md
├── LICENSE                  # Apache 2.0
└── README.md

Guidelines for agents working in this repo

• Do not duplicate generic metavr docs. If a skill needs baseline metavr command guidance, prefer docs/metavr-cli.md or skills/metavr-cli/.
• Keep SKILL.md under 500 lines. Move detailed content to references/ files.
• References should be one level deep. SKILL.md links to references/*.md. Reference files should not link to other reference files.
• Descriptions must be third-person. Use "Analyzes..." not "Analyze...". Include "Meta VR" and "Horizon OS" in every skill description.
• Be concise. Agents already know general programming concepts. Only document Meta VR-specific details, metavr commands, and platform-specific gotchas.