Guide · Agent skill

How to use the Native App Performance Profiling agent skill

Updated 2026-11-02 · written with AI from the project's own documentation and checked against our catalogue data

The native-app-performance skill is a guide plus three helper scripts that let an AI agent profile a native macOS app's CPU use from the terminal, using Apple's xctrace tool instead of the Instruments app. It is written for macOS or iOS developers who want to find slow code paths, and for anyone automating performance checks on a Mac. After reading this page you will know how to install the skill, how to ask an agent to use it, and what it needs on your machine.

Native App Performance Profilingsteipete/agent-scripts · MIT Download the skill

Quick start

1Check requirements. Confirm you are on macOS with Xcode command line tools, Python 3, ripgrep and vmmap available.
2Install the skill. Unzip the downloaded ZIP into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills.
3Ask for a profile. Describe the slow action and the app in plain words, naming the binary if you have it.
4Record the trace. The agent records a Time Profiler trace by attaching to a running process or launching the binary, while you trigger the slow path.
5Extract and symbolicate. The agent exports time samples to XML, reads the runtime __TEXT load address, and resolves symbols against the binary.
6Review the hotspots. Read the ranked list of top app functions and the optimisation suggestions the agent draws from it.

What an agent skill is and what this one does

An agent skill is a folder containing a SKILL.md file and optional scripts that an AI agent can read and use when a request matches the skill's description. This one covers native app performance: the agent records a Time Profiler trace with xctrace, exports the sample data, maps memory addresses to function names using the app binary, and lists the functions that consume the most time so it can suggest where to optimise.

The skill does not open Apple's Instruments app. Its workflow is CLI-only, meaning every step runs from the terminal.

Records a Time Profiler trace, either by attaching to a running process or by launching a binary.
Exports time-sample XML from the trace.
Finds the runtime __TEXT load address of the app so symbols can be resolved.
Symbolicates the samples and ranks the top app functions by time.

Install the skill (ZIP download or Claude app upload)

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

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

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

Check the requirements before you start

The skill only works on macOS with Xcode command line tools installed. The scripts depend on xcrun and xctrace, plus otool, vmmap and ripgrep (rg), and Python 3 is needed to run the scripts. The SKILL.md also references atos for symbolication. If these tools are missing, the scripts will fail.

macOS with Xcode command line tools (provides xcrun and xctrace)
otool (ships with Xcode tools)
vmmap (macOS system tool)
ripgrep (rg), used in the SKILL.md example
Python 3 to run the scripts
atos, referenced for symbolication in the notes

Trigger the skill with a natural request

You do not need to type a special command. Describe the problem in plain terms and mention the app and the slow action. The agent should match the request to the skill when it involves profiling, traces, CPU use or hotspots in a native app.

Good requests name the binary and the action you want to examine, for example opening a menu or refreshing a list. The SKILL.md notes that the slow path must run during the capture, so say what you will do while recording.

"Profile the CPU use of my local build while I open and close the preferences menu."
"Record a 90 second Time Profiler trace of MyApp attached to pid 4312 and tell me the top hotspots."
"Why does refreshing the sidebar in my Mac app feel slow? Use a Time Profiler trace to find out."

Run the workflow: record, extract, symbolicate, rank

The skill's quick start has five steps. First, record with xctrace, either attaching to a process you started yourself or launching a binary directly. Second, extract the time samples to XML. Third, find the runtime __TEXT load address with vmmap while the app is running. Fourth, run the ranking script with the sample XML, the binary path and that load address.

The notes recommend confirming you are profiling the correct binary, since a local build and the copy in /Applications may differ, and preferring a direct binary path for --launch. If stacks come back empty, capture for longer or avoid idle sections. For flag details, the source points to xcrun xctrace help record and xcrun xctrace help export.

Attach to a running app with --attach <pid>.
Launch a binary with --launch -- followed by the binary path.
Use --time-limit to control capture length, for example 90s.
Check flags with xcrun xctrace help record and xcrun xctrace help export.

xcrun xctrace record --template 'Time Profiler' --time-limit 90s --output /tmp/App.trace --attach <pid>
scripts/extract_time_samples.py --trace /tmp/App.trace --output /tmp/time-sample.xml
vmmap <pid> | rg -m1 "__TEXT" -n
scripts/top_hotspots.py --samples /tmp/time-sample.xml --binary /path/App.app/Contents/MacOS/App --load-address 0x100000000 --top 30

Included files and what they do

The skill ships with a guide and three scripts. You can run the scripts yourself, or let the agent run them as part of its workflow.

scripts/record_time_profiler.sh: records via attach or launch.
scripts/extract_time_samples.py: exports time-sample XML from a trace.
scripts/top_hotspots.py: symbolicates and ranks top app frames.
SKILL.md: the instructions the agent reads.

Avoid common mistakes (gotchas)

The load address changes between runs because of ASLR, so you must read the runtime __TEXT address from vmmap each time rather than reusing an old value. If you rebuild the app, update the --binary path, because symbols must match the trace.

Do not reuse a load address from an earlier run; get a fresh one with vmmap.
After a new build, point --binary at the new binary.
Only profile apps you have permission to profile.

What people use it for

Finding which function dominates CPU time when a menu opens slowly.
Checking whether a refresh action spends its time in app code or elsewhere.
Running repeatable Time Profiler captures from a script on a Mac.
Asking an agent to explain a trace and suggest where to look first.

Frequently asked questions

How do I install the native-app-performance skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.

What do I need to run it?

You need macOS with Xcode command line tools, which provide xcrun and xctrace. The scripts also need otool, vmmap, ripgrep (rg) and Python 3, and atos is referenced for symbolication.

Is the native-app-performance skill free?

The skill is published under the MIT licence. Check the licence file in the source repository for the full terms.

Can I use it for web apps or Electron apps?

No. The tools only handle Apple binaries and xctrace traces, so web, Electron and other non-native code is the wrong tool for this skill.

Why does the trace show empty stacks?

The source suggests capturing for longer or avoiding idle sections, and making sure you trigger the slow action during the recording.

Does the skill use the network or run scripts?

It runs scripts, which is why you should review them before use. It does not use the network, according to this listing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are a macOS or iOS developer, or an engineer scripting performance checks on a Mac, and you want an agent to run Time Profiler traces from the terminal. Pick something else for web, Electron or other non-native apps, or if you do not have Xcode command line tools and cannot install them.

Download the skill