How to use the Android Profiler agent skill

What is an agent skill, and what does this one do?

An agent skill is a folder of instructions and supporting files that an AI agent reads when a task matches the skill's description. The agent follows the workflows in the folder rather than guessing at the process. The main entry point is SKILL.md, which tells the agent to route recording requests through a recording orchestrator and analysis requests through an analysis orchestrator.

This skill covers two broad jobs. On the recording side, it guides capture of system traces, CPU call stacks, Vulkan GPU/DRM memory, and Java or native heap profiles. On the analysis side, it reads Perfetto trace files to look for UI jank, frame drops, ANRs, slow app startup, Binder/IPC storms, thread scheduling stalls, battery drain, modem power rails, kernel wake locks, memory pressure, Low Memory Kills, OOMs, leaks and allocation churn. It also supports A/B baseline comparisons to find regressions and ad hoc PerfettoSQL queries.

Install the android-profiler skill

Download the ZIP for the skill from this page and unzip it. For a personal setup, place the unzipped folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder.

You can also upload the skill in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload the skill there.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills

What do you need before you start?

Recording needs an Android device or emulator that is reachable through adb. Analysis needs Perfetto trace processor tooling, which the workflow files reference, and trace files that you supply. Most workflows need recorded data, so if you have no device and no trace files, this skill cannot do much on its own.

• An Android device or emulator reachable through adb, for recording
• Perfetto trace processor tooling, for trace analysis and SQL queries
• Trace files you supply, for analysis

How do you trigger the skill with a natural request?

You do not need to name the skill or mention profiling. Describe the problem in plain words and say what you have. The agent will ask a clarifying question if the request is unclear, because the skill tells it not to guess your intent.

If you have several goals, such as checking a trace for jank and also for memory leaks, the agent is directed to keep them as separate analyses rather than merging them.

• "My app stutters when I scroll the feed on this device. Can you check trace.perfetto-trace for jank?"
• "Why is cold start of com.example.sample taking so long? Here is the trace."
• "Compare baseline.perfetto-trace with the new build trace and find the regression."
• "Write a PerfettoSQL query that lists the longest slices on the main thread in this trace."

Examples of what the agent does

For a jank investigation, the agent first clarifies the symptom and the affected app, then follows the trace analysis workflow step by step. For a recording task, it runs the pre-flight checks in the recording orchestrator before capturing data. For a SQL request on an existing trace, it follows the PerfettoSQL workflow, which covers both executing queries against a trace and drafting queries when no trace is attached.

• Jank: clarify symptom and victim app, then investigate using the CPU, graphics and other hint files.
• Startup or ANR: identify the target process and analyze the relevant trace data.
• A/B regression: identify the baseline trace and compare it against the regressed trace.
• Ad hoc query: draft or run a PerfettoSQL query against the trace file.

Safety notes: scripts and network

This skill runs scripts. It does not use the network. Recording traces can capture app and system activity, so use a test device or get consent before recording on a device that other people depend on or that holds sensitive data. The skill diagnoses and reports; it does not change your app's code automatically.

• Runs scripts: yes
• Uses network: no
• Use test devices or get consent for sensitive production devices

Tips for better results

Give the agent a specific symptom, the app's package name, and the trace file path. When you have a baseline and a regressed build, provide both traces and say which is which, since the workflow asks you to identify the baseline.

• Name the symptom: jank, slow startup, ANR, memory leak, battery drain.
• Name the app or process, for example com.example.sample.
• For regressions, supply a baseline trace and a changed trace.