Skip to content
Get packs

Instruments Profiling

Guides the agent to record and analyze macOS/iOS app performance traces with xctrace

Source Download skill
Repository
steipete/agent-scripts
Stars
7,433
Licence
MIT
Files
1 file

What it does

This skill teaches an AI agent how to measure where a native Mac or iPhone app spends its time, using Apple's Instruments tool through the command-line xctrace utility. Once installed, the agent knows how to start a Time Profiler recording (launching the app or attaching to a running process), make sure it is profiling the correct build, export the recorded call stacks, and summarize the slowest code paths. It also covers common pitfalls such as the wrong copy of an app being profiled and empty traces.

Great for

  • Developers debugging slow startup or sluggish behavior in macOS or iOS apps
  • Engineers who want an agent to run and interpret Instruments traces instead of clicking through the UI
  • Teams automating repeatable performance captures and comparing exported stacks over time

Skip it if

  • Users without Xcode and a Mac, since xctrace and Instruments only run on macOS (the skill cannot help on other platforms)
  • Web, Android or cross-platform performance work, which this skill does not cover
  • Running it against apps you do not own or have permission to inspect, since profiling attaches to live processes and reads their execution data

Try asking

  • “Profile my local build of MyApp for 60 seconds during startup and tell me the top hot functions”
  • “Attach to the running process with PID 4321 and record a Time Profiler trace of the slow refresh”
  • “Export the time-profile table from this .trace file and aggregate the heaviest stacks”
  • “Record my connected iPhone by UDID while I reproduce the scrolling lag”
Step-by-step guide: how to use Instruments ProfilingInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 1 original files, the MIT licence and an attribution note.

    instruments-profiling.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip instruments-profiling.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip instruments-profiling.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Point the agent at the exact binary path (App.app/Contents/MacOS/App) so it does not profile an installed copy in /Applications by mistake
  • Ask the agent to confirm the process path with ps before trusting results, and to trigger the slow action during the recording window
  • Keep exports filtered with XPath and have the agent summarize them rather than printing huge XML to the terminal

What's inside

  • SKILL.md

Redistributed unmodified from steipete/agent-scripts under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.