instruments-profiling-pro
Skill5 starsChanged 10 days agoMITView on GitHub
Profiles Apple-platform apps from the command line with xctrace (Instruments) — recording traces, exploring .trace and .atrc files with toc / list tracks / show, reading and arranging call trees, symbolicating, keeping output small enough to read, and triaging hangs (busy vs. blocked, severity tiers). Use when an app is slow, uses too much CPU, freezes or hangs, when measuring an optimization, or whenever a trace file needs reading.
In this repository19 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- app-intents-proSkill
- coredata-swift6-proSkill
- motion-design-proSkill
- store-compliance-proSkill
- swift-accessibility-proSkill
- swift-adaptive-layout-proSkill
- swift-concurrency-proSkill
- swiftdata-proSkill
- swift-design-system-proSkill
- swift-docc-proSkill
- swift-error-handling-proSkill
- swift-logging-proSkill
- swift-memory-storage-proSkill
- swift-modularization-proSkill
- swift-package-proSkill
- swift-testing-proSkill
- swiftui-proSkill
- xcode-security-proSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 25
Measure, don't guess: Every claim about a hot spot cites a track and a number from the trace.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Find out where an app spends time, using xctrace, Instruments' command-line interface, so an agent can record and read traces without the Instruments UI.
Sources. Grounded in Apple's Instruments documentation and in the xctrace skill Apple bundles with Xcode 27, which Artem Novichkov extracted and published in
artemnovichkov/xcode-skills. The guidance is rewritten and condensed for this bundle, not copied.xctracechanges between Xcode releases: refresh the command surface withxctrace helpbefore relying on any flag here.
Process:
- State the question first: which interaction is slow, on which device and build, and what "fixed" means (a number). Profile a Release-like build on a real device; the simulator and Debug builds mislead.
- Record or open the trace and explore it with
references/xctrace.md(toc→list tracks→show). - For freezes and hangs, triage with
references/hangs.mdbefore reading call trees. - Find the heaviest path in the call tree, map it to source, and propose one change.
- Measure again with the same template, device, and steps, and report before / after numbers.
Core Instructions
- Measure, don't guess. Every claim about a hot spot cites a track and a number from the trace.
- Keep output readable.
triageprints hundreds of lines andshowcan print far more. Redirect to a file in the scratch directory and read slices; never stream a whole call tree into context. - Symbolicate before reading. Hex addresses mean the dSYM didn't match (
dwarfdump --uuidon both sides). - One change per measurement. Two fixes in one run hide which one helped.
- Cross-reference: memory growth and leaks go to
swift-memory-storage-pro; main-actor and Task structure toswift-concurrency-pro; SwiftUI invalidation toswiftui-pro; signposts for custom intervals toswift-logging-pro(OSSignposter).
Output Format
Report the question, the trace (template, device, build), the finding with its numbers and source location, the proposed change, and the before / after measurement.
Example:
Scrolling the feed hangs for 640 ms (Hang tier) on first load. Main thread busy: 82% of samples under FeedViewModel.load() → JSONDecoder.decode (FeedViewModel.swift:48). Move decoding off the main actor; after the change the longest main-thread interval is 90 ms (no hang reported).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

