Agent skill

Hz Simpleperf Debug

by meta-quest in meta-quest/agentic-tools

Profiles Meta VR and Horizon OS application CPU performance using simpleperf — workload classification, CPU hotspot recording, kernel overhead measurement.

Apache-2.0Auto-check passedGame Development

Install Hz Simpleperf Debug

skills CLI
$ npx skills add meta-quest/agentic-tools --skill hz-simpleperf-debug -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install meta-quest/agentic-tools hz-simpleperf-debug --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/meta-quest/agentic-tools.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/hz-simpleperf-debug .claude/skills/hz-simpleperf-debug && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
hz-simpleperf-debug
GitHub stars
213
Token cost
~2k tokens
SKILL.md length
804 words
Files
4 (incl. references)
Skills in repo
34
Repo updated
First seen
Licence
Apache-2.0

At a glance

Profiles Meta VR and Horizon OS application CPU performance using simpleperf — workload classification, CPU hotspot recording, kernel overhead measurement.

  • Works in 6 steps: Classify the Workload → Record CPU Hotspots → Measure Kernel Overhead → …
  • Diagnosing whether an app is CPU-bound
  • SKILL.md covers When to Use, VR Performance Context, metavr Setup and Quick Start Workflow, plus 3 more sections
  • Calls npx and adb

What it does

Hz Simpleperf Debug is an agent skill from meta-quest/agentic-tools. Profiles Meta VR and Horizon OS application CPU performance using simpleperf — workload classification, CPU hotspot recording, kernel overhead measurement. Use when diagnosing whether an app is CPU-bound, memory-bound, or I/O-bound on Meta VR devices. Build paths: all Meta VR app stacks; use hz-quest-verify-first if the build path is unclear.

Its SKILL.md is about 2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 4 other files, including reference files (for example `references/cpu-hotspot-analysis.md`, `references/kernel-overhead.md` and `references/workload-classification.md`).

It sits in Game Development. The repository describes itself as: Agent Skills for Meta Quest/Horizon OS VR Development. The licence is Apache-2.0.

When your agent uses it

  • Diagnosing whether an app is CPU-bound
  • I/O-bound on Meta VR devices

Example prompts

  • “Use the hz-simpleperf-debug skill to profile Meta VR and Horizon OS application CPU performance using simpleperf — workload classification, CPU…”
  • “/hz-simpleperf-debug”

Requirements

  • Node.js
  • Pre-approved tools (allowed-tools): Bash(metavr:*), Bash(hzdb:*)

Workflow steps

6 steps, taken from the step headings in SKILL.md.

  1. Classify the Workload
  2. Record CPU Hotspots
  3. Measure Kernel Overhead
  4. Classify First
  5. Measure Kernel Overhead
  6. Combine with Perfetto

What it can do on your machine

Read from SKILL.md and the folder at commit 3a8553d. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Bash(metavr:*)
    • Bash(hzdb:*)

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • npx
    • adb

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use npx, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Hz Simpleperf Debug loads about 2k tokens when it runs, and up to ~5.1k if it reads all its reference files. Until then it costs about 91 tokens; SKILL.md has 804 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~91
When it runs · the whole SKILL.md, loaded when a task matches
~2k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~5.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from meta-quest/agentic-tools at commit 3a8553d, republished under its Apache-2.0 licence (© meta-quest). 804 words, ~1,953 tokens.

Download SKILL.mdSave it as .claude/skills/hz-simpleperf-debug/SKILL.md (or your agent's skills folder). This skill also uses 3 other files; get the full folder from GitHub.
name
hz-simpleperf-debug
description
Profiles Meta VR and Horizon OS application CPU performance using simpleperf — workload classification, CPU hotspot recording, kernel overhead measurement. Use when diagnosing whether an app is CPU-bound, memory-bound, or I/O-bound on Meta VR devices. Build paths: all Meta VR app stacks; use hz-quest-verify-first if the build path is unclear.
allowed-tools
Bash(metavr:*), Bash(hzdb:*)
license
Apache-2.0

Simpleperf Debug Skill

When to Use

Use this skill when you need hardware-level CPU performance insights on Meta VR devices:

  • Classifying whether an app is CPU-bound, memory-bound, or I/O-bound
  • Finding CPU hotspot functions consuming the most cycles
  • Measuring kernel vs userspace CPU overhead per thread
  • Identifying cache-thrashing or branch-prediction issues
  • Supplementing Perfetto trace analysis with hardware PMU counter data

This skill complements hz-perfetto-debug. Perfetto shows what your app is doing over time. Simpleperf shows where the CPU is spending hardware cycles — cache misses, branch mispredictions, and instruction throughput that Perfetto can't see.

VR Performance Context

Meta VR devices run on mobile ARM SoCs with strict thermal and power budgets. CPU-bound apps hit frame drops when:

Refresh RateCPU Frame BudgetNotes
120 Hz8.3 msTight — simpleperf critical for finding hotspots
90 Hz11.1 msDefault target for most apps
72 Hz13.9 msFallback for heavier apps

Simpleperf's hardware counters reveal bottlenecks invisible to software tracing.

metavr Setup

Simpleperf profiling is powered by the metavr CLI — install the standalone binary on your PATH (see the metavr-cli skill), or invoke via npx with no install:

bash
metavr --version

Examples below use the bare metavr command; if you use the npm distribution, prefix with npx -y. Connect your Meta VR device via USB with developer mode enabled.

Quick Start Workflow

1. Classify the Workload

Before optimizing, determine the bottleneck type:

bash
# Classify the foreground app's workload (10-second sample)
metavr perf simpleperf classify

# Target a specific app
metavr perf simpleperf classify --app com.example.myapp

# Custom duration
metavr perf simpleperf classify --duration 15

Returns a classification with evidence:

ClassificationIndicatorOptimization Strategy
CPU-boundHigh IPC, low stall ratioOptimize algorithms, reduce draw calls, batch work
Memory-boundHigh stall ratio (stalled-cycles-backend / cpu-cycles)Reduce cache misses, improve data locality, shrink working set
I/O-boundHigh context switches per secondReduce blocking I/O, use async, minimize thread contention
2. Record CPU Hotspots

Capture a CPU cycle profile to find the most expensive functions:

bash
# Record CPU hotspots for the foreground app
metavr perf simpleperf record

# Custom frequency and duration
metavr perf simpleperf record --frequency 4000 --duration 10

# Target a specific app
metavr perf simpleperf record --app com.example.myapp

The recording samples CPU cycles at the specified frequency (default 4000 Hz) and generates a profile showing which functions consume the most CPU time.

3. Measure Kernel Overhead

Determine how much CPU time is spent in kernel vs userspace per thread:

bash
# Measure kernel overhead for the foreground app
metavr perf simpleperf kernel-overhead

# Custom duration
metavr perf simpleperf kernel-overhead --app com.example.myapp --duration 10

Returns per-thread breakdown of user-mode vs kernel-mode CPU cycles. High kernel overhead (>20%) in a thread suggests:

  • Excessive syscalls (file I/O, memory allocation)
  • Driver overhead (GPU command submission, sensor access)
  • Lock contention in kernel synchronization primitives

Analysis Workflow

Step 1: Classify First

Always start with classification. This prevents wasting time optimizing the wrong thing.

bash
metavr perf simpleperf classify --app com.example.myapp --duration 10

Decision tree based on results:

  • CPU-bound → Record hotspots (Step 2a), look at top functions
  • Memory-bound → Record with cache-miss events, check data access patterns
  • I/O-bound → Check kernel overhead, look at thread contention in Perfetto
Step 2a: CPU-Bound Apps — Find Hotspots
bash
metavr perf simpleperf record --app com.example.myapp --duration 10

Review the top functions by CPU cycle consumption. Common VR hotspots:

Function PatternLikely CauseFix
Physics.* / PhysXComplex physics simulationReduce collider count, simplify meshes, increase fixed timestep
Render* / Draw*Too many draw callsBatch materials, use GPU instancing, reduce unique materials
GC_* / gc_allocGarbage collection pressurePool allocations, avoid per-frame allocations
memcpy / memmoveLarge data copiesUse references, reduce buffer sizes, avoid unnecessary copies
LZ4_* / compressAsset decompressionPre-decompress, use lighter compression, cache results
Show full SKILL.md (302 more words)Show less
Step 2b: Memory-Bound Apps — Check Cache Behavior

If classification shows memory-bound, the issue is likely cache misses or memory bandwidth:

  • Large working sets thrashing L1/L2 cache
  • Random access patterns defeating prefetcher
  • False sharing between threads on adjacent cache lines

Use Perfetto hz-perfetto-debug to correlate memory-bound regions with specific code paths.

Step 3: Measure Kernel Overhead
bash
metavr perf simpleperf kernel-overhead --app com.example.myapp

Interpreting results by thread:

ThreadExpected Kernel %High Kernel % Indicates
Main/Game thread< 5%Excessive file I/O, logging, or allocations
Render thread5-15%Normal (GPU driver overhead). >20% = driver issue
Worker threads< 5%Thread synchronization overhead
Audio thread< 10%Normal for audio HAL calls
Step 4: Combine with Perfetto

Simpleperf tells you where cycles go. Perfetto tells you when and in what context. Use together:

  1. Simpleperf classification reveals the bottleneck type
  2. Simpleperf hotspot recording identifies the expensive functions
  3. Perfetto trace (metavr perf capture) shows when those functions run relative to frame boundaries
  4. Use metavr perf query to correlate function timing with frame drops

Common Pitfalls

  • Don't profile in thermal throttling. Let the device cool before recording — throttled clocks distort cycle counts. Check thermal state first with metavr device info.
  • Sample duration matters. Short recordings (<5s) may not capture representative behavior. Use at least 10 seconds for classification.
  • simpleperf requires shell access. If adb shell simpleperf fails, ensure developer mode is enabled and USB debugging is authorized.
  • Frequency vs accuracy tradeoff. Higher sampling frequency (>8000 Hz) can perturb the workload on mobile SoCs. Default 4000 Hz is a good balance.
  • Classification is a snapshot. An app can be CPU-bound during gameplay and I/O-bound during scene loads. Profile the specific scenario you're optimizing.

References

For detailed guides on specific topics, see:

© meta-quest, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 3 other files (references) in skills/hz-simpleperf-debug of meta-quest/agentic-tools.

  • SKILL.md
  • references/cpu-hotspot-analysis.md
  • references/kernel-overhead.md
  • references/workload-classification.md

Open the folder on GitHubat commit 3a8553d

Compare with similar skills

Hz Simpleperf Debug next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Hz Simpleperf Debug compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Hz Simpleperf Debug this skillmeta-quest/agentic-tools213—~2kAutomated safety check: PassApache-2.0
Image to Three.js Modelimg2threejs/img2threejs18k1 repos~8.2kAutomated safety check: PassApache-2.0
Web CloneJane-xiaoer/claude-skill-web-clone1k1 repos~2.7kAutomated safety check: PassMIT
Threejs Game Directormajidmanzarpour/threejs-game-skills2.4k—~2.2kAutomated safety check: PassMIT
Game Asset Generatorhtdt/godogen7.1k—~2.8kAutomated safety check: PassMIT
Threejs Gameplay Systemsvalkor-ai/loom1.2k1 repos~1.4kAutomated safety check: PassApache-2.0

Similar skills

  • Image to Three.js Model

    img2threejs/img2threejs

    Rebuilds the object in a reference image as a procedural, animation-ready Three.js model written entirely in code, using staged sculpting with quality checks.

    18k GitHub starsUsed in 1 repo~8.2k tokens
    Game DevelopmentAuto-check passed
  • Web Clone

    Jane-xiaoer/claude-skill-web-clone

    网站复刻 / 克隆方法论。USE WHEN 用户说 复刻网站、克隆网站、clone website、抄个站、仿站、 照着这个站做一个、reproduce site、还原某个网页效果、把这个站搬下来改成我的、 复刻某个交互/WebGL/Canvas/Three.js 效果。提供「先拿真源码 → 判路径 → 逆向拆解 → 搭工程 → 替换内容」的可移植决策树,覆盖静态站 /…

    1k GitHub starsUsed in 1 repo~2.7k tokens
    Game DevelopmentAuto-check passed
  • Threejs Game Director

    majidmanzarpour/threejs-game-skills

    Entrypoint for building, upgrading, and finishing Three.js browser games.

    2.4k GitHub stars~2.2k tokensUpdated 9 days ago
    Game DevelopmentAuto-check passed
  • Generates game art from text prompts: PNG images, GLB 3D models, rigged characters, animations and sprites, with background removal.

    7.1k GitHub stars~2.8k tokensUpdated 6 days ago
    Game DevelopmentAuto-check passed
  • Build and iterate playable Three.js game systems: starter scaffold, architecture, design briefs, core loops, level and encounter design, entities, input, camera, collision and physics, scoring…

    1.2k GitHub starsUsed in 1 repo~1.4k tokens
    Game DevelopmentAuto-check passed
  • Uloop Execute Dynamic Code

    CyberAgentGameEntertainment/NovaShader

    Execute C with Unity APIs when existing uloop tools cannot inspect or edit enough.

    1.6k GitHub starsUsed in 1 repo~1.9k tokens
    Game DevelopmentAuto-check passed

More from meta-quest/agentic-tools

All 34 skills in this repo
  • Hz Android 2D Porting

    meta-quest/agentic-tools

    Guides porting existing Android 2D apps to Meta VR and Horizon OS — input adaptation, panel layout, and design requirements.

    213 GitHub stars~2.1k tokensUpdated 13 days ago
    Auto-check passed
  • Hz API Upgrade

    meta-quest/agentic-tools

    Upgrades Meta VR apps to newer Horizon OS SDK versions — migration guides, deprecated API replacements, changelog.

    213 GitHub stars~1.8k tokensUpdated 13 days ago
    Auto-check passed
  • Hz Iwsdk Webxr

    meta-quest/agentic-tools

    Builds WebXR experiences for Meta VR and Horizon OS using the Immersive Web SDK (IWSDK) — ECS architecture, Three.js integration, spatial UI.

    213 GitHub stars~3k tokensUpdated 13 days ago
    Auto-check passed
  • Hz Metavrx Layout SDK

    meta-quest/agentic-tools

    Build multi-window Meta Horizon OS experiences with the MetaVrx Layout SDK in Jetpack Compose or React Native.

    213 GitHub stars~855 tokensUpdated 13 days ago
    Auto-check passed
  • Hz New Project Creation

    meta-quest/agentic-tools

    Scaffolds new Meta VR and Horizon OS projects after the build path is selected — Standard Android, Meta Spatial SDK, Unity, Unreal, or WebXR.

    213 GitHub stars~2.3k tokensUpdated 13 days ago
    Auto-check passed
  • Hz Perfetto Debug

    meta-quest/agentic-tools

    Analyzes Meta VR and Horizon OS VR performance using Perfetto traces — frame timing, CPU/GPU bottlenecks, render pass analysis.

    213 GitHub stars~2.8k tokensUpdated 13 days ago
    Auto-check passed

Questions about Hz Simpleperf Debug

What does Hz Simpleperf Debug do?

Profiles Meta VR and Horizon OS application CPU performance using simpleperf — workload classification, CPU hotspot recording, kernel overhead measurement. Hz Simpleperf Debug is an agent skill from meta-quest/agentic-tools. Profiles Meta VR and Horizon OS application CPU performance using simpleperf — workload classification, CPU hotspot recording, kernel overhead measurement.

When should I use Hz Simpleperf Debug?

Hz Simpleperf Debug fits situations like: diagnosing whether an app is CPU-bound; I/O-bound on Meta VR devices.

How do I install Hz Simpleperf Debug in Claude Code?

Run `npx skills add meta-quest/agentic-tools --skill hz-simpleperf-debug -a claude-code`. Or copy the skill folder (skills/hz-simpleperf-debug in meta-quest/agentic-tools) into .claude/skills/hz-simpleperf-debug in your project. Claude Code loads it when a task matches its description.

How do I install Hz Simpleperf Debug in Codex?

Run `npx skills add meta-quest/agentic-tools --skill hz-simpleperf-debug -a codex`. Or copy the skill folder (skills/hz-simpleperf-debug in meta-quest/agentic-tools) into .agents/skills/hz-simpleperf-debug in your project. Codex loads it when a task matches its description.

Can I use Hz Simpleperf Debug in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add meta-quest/agentic-tools --skill hz-simpleperf-debug -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/hz-simpleperf-debug, .gemini/skills/hz-simpleperf-debug, .github/skills/hz-simpleperf-debug and .opencode/skills/hz-simpleperf-debug in your project.

What does Hz Simpleperf Debug need to run?

Going by SKILL.md and its folder, Hz Simpleperf Debug needs the command-line tools its instructions call (npx and adb). Our summary lists: Node.js. Its frontmatter pre-approves these tools: Bash(metavr:*), Bash(hzdb:*).

Does Hz Simpleperf Debug access the network?

SKILL.md contains no URLs. Its commands use npx, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Hz Simpleperf Debug safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Hz Simpleperf Debug use?

Hz Simpleperf Debug is published under the Apache-2.0 licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Hz Simpleperf Debug use?

About 2k tokens (SKILL.md is roughly 7.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 3.1k tokens, read only when the agent opens those files.

What are the alternatives to Hz Simpleperf Debug?

Skills that share tags, products or a category with Hz Simpleperf Debug: Image to Three.js Model (img2threejs/img2threejs, 18k stars), Web Clone (Jane-xiaoer/claude-skill-web-clone, 1k stars), Threejs Game Director (majidmanzarpour/threejs-game-skills, 2.4k stars) and Game Asset Generator (htdt/godogen, 7.1k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Hz Simpleperf Debug?

meta-quest (a GitHub organization) maintains it in meta-quest/agentic-tools, which has 213 GitHub stars. The repository holds 34 skills in this directory. The repository was last updated on September 24, 2026.

Source: meta-quest/agentic-tools on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.