How to use the Instruments Profiling agent skill

What the skill makes the agent do

Once installed, the agent knows how to start a Time Profiler recording, either by launching your app or by attaching to a process that is already running. It records to a .trace file, exports the recorded call stacks, and summarizes the slowest code paths.

The skill also covers common mistakes, such as profiling the wrong copy of an app or getting an empty trace, and tells the agent how to check for them.

• Records Time Profiler traces with xcrun xctrace
• Launches an app binary or attaches to a running PID
• Exports call stacks from the trace for analysis
• Checks that the profiled process is the build you intended

Install the instruments-profiling skill

Download the skill ZIP from this page and unzip it. The skill is a folder containing a SKILL.md file. Put that folder in one of these locations:

Personal skills folder: ~/.claude/skills/ (available to all your projects).

Project folder: .claude/skills/ inside your project (available only to that project).

You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

• Option A: unzip into ~/.claude/skills/
• Option B: unzip into a project's .claude/skills/ folder
• Option C: upload the ZIP in Settings → Capabilities → Skills

Set up macOS, Xcode and permissions

The skill needs macOS with Xcode, which provides the xcrun and xctrace tools. Your app must exist as a built binary or bundle. Debug symbols are recommended so the stacks show readable function names.

xctrace may need permission to run. Go to System Settings → Privacy & Security → Developer Tools and allow Terminal or Xcode. For iOS, you need a connected device, identified by name or UDID.

• macOS with Xcode installed
• Terminal or Xcode allowed under Developer Tools permission
• A built app binary or bundle
• Debug symbols (recommended)
• For iOS: a connected device identified by name or UDID

Trigger the skill with natural requests

You do not need to name the skill or any commands. Describe the performance problem and point the agent at your build. The skill applies when you ask for profiling or stack analysis of a native app.

Be specific about the slow behavior (startup, a button press, scrolling) and the app's location. The more precise you are, the more useful the capture will be.

• "Profile the startup of my local build at ./build/MyApp.app and tell me the top hot functions."
• "Attach to the running MyApp process and record 60 seconds of Time Profiler data while I scroll the list."
• "Record a Time Profiler trace of my iPhone app and summarize the slowest call paths."

Record a Time Profiler trace

To launch an app and record it, the agent runs xctrace with the Time Profiler template, a time limit, an output path and the target after --. To attach to a running app, launch it yourself, get its PID, and use --attach instead. The skill lists the templates available on your machine first, and it uses xctrace help record for flag details because xctrace --help is not a valid subcommand.

To open the result in the Instruments app, the agent runs open -a Instruments on the .trace file.

• Launch: record with --launch -- /path/To/App.app
• Attach: record with --attach <pid>
• Open the result: open -a Instruments /tmp/App.trace

Make sure you profile the right build

The main gotcha is that Instruments can profile the wrong app, for example an installed copy in /Applications, when LaunchServices resolves a different bundle. The skill tells the agent to prefer the direct binary path for a predictable launch, and to explicitly target your local build if both exist.

After launch, the agent should confirm the process path before trusting the trace. Checking the process with ps is the recommended way to do this.

• Prefer the direct binary path, e.g. /path/App.app/Contents/MacOS/App
• If you launch a .app, open it with open -n and verify with ps -p <pid> -o comm= -o command=
• If both /Applications/App.app and a local build exist, target the local build path

Export stacks and analyze them

The skill can export the trace's tables and then the raw time-profile samples. First it lists the tables with --toc, then exports a specific table with an XPath query. Time-profile exports can be very large, so the skill filters them and aggregates the data in a script (Python or Rust are mentioned) rather than printing it to the terminal.

Exported stacks can be compared between runs, which helps when you are checking whether a change made things faster.

• List tables with --toc
• Export time-profile samples with an XPath filter and --output
• Aggregate stacks in a script instead of printing the XML

Use the Instruments UI and fix common problems

If you prefer the visual tool, the skill suggests the Time Profiler template, recording the slow path (startup or steady-state), and call tree options such as Hide System Libraries, Invert Call Tree, Separate by Thread, and focusing on hot frames and call counts.

If a trace is empty, the app probably exited quickly or never reached the slow work. Record for longer and trigger the workload while recording. For iOS, the skill notes to use xcrun xctrace list devices to find the device and --device <UDID> for device runs.

• Empty trace: record longer and trigger the work during the capture
• Wrong app: use the direct binary path or --attach with a known PID
• Permission prompt: allow Terminal or Xcode under Developer Tools
• Missing function names: build with debug symbols