How to use the Apple App Performance Profiling agent skill

What the skill makes the agent do

When the skill is active, the agent follows a fixed playbook instead of guessing. It first identifies the category of problem from your report, traces, logs or code, then reads only the matching reference file. The categories are responsiveness (hangs, stutters, high CPU), memory (leaks, growth, OOM crashes), launch time, and energy (battery drain, thermal issues, network waste).

The agent is directed to profile on a real device in a Release build with representative data, to inspect the code path the profile points to, to apply the smallest targeted fix, and to measure again before and after the change. For a pre-release audit it uses a review checklist covering responsiveness, memory, launch and energy.

• Picks the profiling tool that fits the symptom, for example Time Profiler for hangs and high CPU, Leaks and Allocations for memory, App Launch for slow starts and Energy Log for battery drain.
• Recommends relevant Xcode Scheme > Run > Diagnostics options such as Main Thread Checker or Thread Sanitizer when they match the suspected issue.
• Suggests a MetricKit subscriber for production monitoring and can add os_signpost markers for ongoing timing.

Install the performance-profiling skill

Download the ZIP for this skill from this page. Unzip it into your personal skills folder at ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill to apply only to that project. The skill's main file is SKILL.md, and it sits alongside the references folder.

If you use the Claude apps instead of the file system, open Settings, go to Capabilities, and upload the skill under Skills. Either way, the agent loads the skill when a request matches its description.

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

Trigger the skill with natural requests

You do not need to type a command. Describe the symptom in ordinary words. The skill's description lists the triggers it responds to: app hangs, stutters, high CPU, memory leaks, memory growth, OOM crashes, slow launch, battery drain, thermal issues, App Store performance readiness, and adding os_signpost or measurement hooks.

You can also name the skill directly with a dollar sign, as the demo prompts in the package do, for example $performance-profiling. Include what you observed, when it happens and, if you have them, the traces or logs.

• "The timeline stutters after I edit for 10 minutes. Where should I look?"
• "Memory keeps growing and does not drop after I close the editor. Help me find the leak."
• "Our app takes too long to reach the first frame. Walk me through an App Launch profile."
• "Prepare a pre-release performance audit for our iOS app."
• "Add os_signpost timing around our sync workflow."

Example of a typical session

The package includes a demo with a fictional symptom: a timeline that starts smoothly but drops frames after 8 to 10 minutes of editing, with memory that keeps growing after the editor is closed. The expected plan in the demo is to record a reproducible signposted editing session, capture Time Profiler and Allocations traces, compare live-object growth before and after closing the editor, inspect retain cycles with Memory Graph, and re-run the same scenario after a narrow fix.

Your own session will follow the same shape: the agent proposes a plan, you run the profiler on a device, and you bring back the results for the agent to interpret.

What you need before you start

The skill gives guidance only. It does not run Instruments for you. You need Xcode and Apple Instruments to carry out the profiling workflows it describes. A physical Apple device is recommended, because the Simulator uses host CPU and memory and so gives less accurate measurements. Energy profiling in particular requires real hardware.

The skill runs no scripts and makes no network calls, according to its package description.

• Xcode and Apple Instruments
• A physical iPhone, iPad or Mac for accurate numbers
• A Release build and representative data

Safety notes: scripts and network

This skill does not run scripts and does not use the network. Its content is Markdown instructions, reference files and a short MetricKit code sample that you choose whether to add to your project. The agent still edits code in your project when you ask it to, so review changes as you would for any code change.

The MetricKit sample reads performance payloads inside your app. It only logs values in the example; any export or upload is something you would have to write yourself.

Tips for better results

Give the agent real measurements. A trace summary or a note of where the hang happens is more useful than a general description. Profile before and after each fix so the improvement is concrete rather than assumed.

Keep the scope narrow. The skill itself recommends the smallest fix that addresses the measured bottleneck, so ask for one problem at a time.

• Use Release builds, close unrelated apps and reproduce with realistic data.
• Ask for a pre-release audit when you want a full pass over all four checklist areas.
• Add os_signpost markers when you need timing visibility over time.