instruments-profiling — Claude Code skill: profiling
The instruments-profiling skill guides macOS and iOS profiling with Instruments and xctrace, from trace capture to stack export. Use it when a native app has a slow path.
MIT 242 installs ★ 7,554 updated 2026-10-20
npx skills add steipete/agent-scripts --skill instruments-profiling -a claude-codeWhat instruments-profiling does
The skill covers Time Profiler runs started with xcrun xctrace and attachments to an existing process. It explains how to pass a binary or app bundle, set a capture duration, save a .trace file, and select an iOS device. It also helps the agent choose the intended app instance.
Trace inspection uses xcrun xctrace export, the trace table of contents, and an XPath expression for time-profile data. The exported XML can then be aggregated in Python or Rust. The workflow includes opening the trace in Instruments and narrowing the Call Tree to relevant frames.
A wrong bundle can invalidate the result because LaunchServices may resolve an installed app instead of the local build. Use a direct binary path or attach to a known PID, then verify the process path. iOS stack analysis also needs debug symbols, and xctrace may require Developer Tools permission for Terminal or Xcode.
What it helps with
- capture a Time Profiler trace for a macOS app
- attach to a running process by PID
- target the local build instead of an installed bundle
- export time-profile samples from a
.tracefile - inspect hot frames in the Call Tree
Example prompts for the agent
- Profile the local app with Time Profiler and save the result to
/tmp/App.trace. - Attach to PID
<pid>, verify the process path, and investigate the slow operation. - Export time-profile data from
/tmp/App.traceto/tmp/time-profile.xmlfor a Python script.
How to install instruments-profiling
1Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill instruments-profiling -a claude-code2Manually: put the files in place
~/.claude/skills/instruments-profiling/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/instruments-profiling/
1Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill instruments-profiling -a codex2Manually: put the files in place
.agents/skills/instruments-profiling/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill instruments-profiling -a cursor2Manually: put the files in place
.cursor/skills/instruments-profiling/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install steipete/agent-scripts skills/instruments-profiling2Manually: put the files in place
.github/skills/instruments-profiling/SKILL.md1Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill instruments-profiling -a gemini-cli2Platform CLI
gemini skills install https://github.com/steipete/agent-scripts --path skills/instruments-profilingManually: put the files in place
.devin/skills/instruments-profiling/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill instruments-profiling -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about instruments-profiling
How do I install instruments-profiling in Claude Code?
Run npx skills add steipete/agent-scripts --skill instruments-profiling -a claude-code, then check ~/.claude/skills/instruments-profiling/SKILL.md.
What does instruments-profiling do?
It guides performance and stack profiling for native macOS and iOS apps with Instruments and xctrace, including trace capture and stack export.
Why can Instruments profile the wrong app?
LaunchServices can resolve an installed app instead of the local build. Target the binary directly or attach to a known PID, then verify the process path.
Source text
SKILL.md · MIT
--- name: instruments-profiling description: "Instruments/xctrace profiling: macOS/iOS traces, binaries, args, exports." metadata: short-description: Instruments profiling for macOS/iOS apps --- # Instruments Profiling (macOS/iOS) Use this skill when the user wants performance profiling or stack analysis for native apps. Focus: Time Profiler, `xctrace` CLI, and picking the correct binary/app instance. ## Quick Start (CLI) - List templates: `xcrun xctrace list templates` - Record Time Profiler (launch): - `xcrun xctrace record --template 'Time Profiler' --time-limit 60s --output /tmp/App.trace --launch -- /path/To/App.app` - Record Time Profiler (attach): - Launch app yourself, get PID, then: - `xcrun xctrace record --template 'Time Profiler' --time-limit 60s --output /tmp/App.trace --attach <pid>` - Open trace in Instruments: - `open -a Instruments /tmp/App.trace` Note: `xcrun xctrace --help` is not a valid subcommand. Use `xcrun xctrace help record`. ## Picking the Correct Binary (Critical) **Gotcha: Instruments may profile the wrong app** (e.g., one in `/Applications`) if LaunchServices resolves a different bundle. Use these rules: - Prefer direct binary path for deterministic launch: - `xcrun xctrace record ... --launch -- /path/App.app/Contents/MacOS/App` - If launching `.app`, ensure it’s the intended bundle: - `open -n /path/App.app` - Verify with `ps -p <pid> -o comm= -o command=` - If both `/Applications/App.app` and a local build exist, explicitly target the local build path. - After launch, confirm the process path before trusting the trace. ## Command Arguments (xctrace) - `--template 'Time Profiler'`: template name from `xctrace list templates`. - `--launch -- <cmd>`: everything after `--` is the target command (binary or app bundle). - `--attach <pid|name>`: attach to running process. - `--output <path>`: `.trace` output. If omitted, file saved in CWD. - `--time-limit 60s|5m`: set capture duration. - `--device <name|UDID>`: required for iOS device runs. - `--target-stdout -`: stream launched process stdout to terminal (useful for CLI tools). ## Exporting Stacks (CLI) - Inspect trace tables: - `xcrun xctrace export --input /tmp/App.trace --toc` - Export raw time-profile samples: - `xcrun xctrace export --input /tmp/App.trace --xpath '/trace-toc/run[@number="1"]/data/table[@schema="time-profile"]' --output /tmp/time-profile.xml` - Post-process in a script (Python/Rust) to aggregate stacks. ## Instruments UI Workflow - Template: Time Profiler - Use “Record” and capture the slow path (startup vs steady-state) - Call Tree tips: - Hide System Libraries - Invert Call Tree - Separate by Thread - Focus on hot frames and call counts ## Gotchas & Fixes - **Wrong app profiled**: LaunchServices resolves installed app instead of local build. - Fix: use direct binary path or `--attach` with known PID. - **No samples / empty trace**: App exits quickly or never hits work. - Fix: longer capture, trigger workload during recording. - **Privacy prompts**: `xctrace` may need Developer Tools permission. - Fix: System Settings → Privacy & Security → Developer Tools → allow Terminal/Xcode. - **Large XML exports**: `time-profile` exports are huge. - Fix: filter with XPath and aggregate offline; don’t print to terminal. ## iOS Specific Notes - Device: use `xcrun xctrace list devices` and `--device <UDID>`. - Launch via Xcode if needed; attach with `xctrace --attach`. - Ensure debug symbols for meaningful stacks. ## Verification Checklist - Confirm trace process path matches target build. - Confirm stacks show expected app frames. - Capture covers the slow operation (startup/refresh). - Export stacks for automated diffing if optimizing.
© steipete · MIT · steipete/agent-scripts