debugging-instruments
Debug iOS apps and profile performance using LLDB, the interactive Memory Graph Debugger, and Instruments. Use for crashes, retain-cycle inspection, hangs, build failures, and generic CPU, memory, energy, or network profiling.
Install / Use
npx skills add dpearson2699/swift-ios-skills --skill debugging-instrumentsInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of debugging-instruments
debugging-instruments scores 89/100 on our quality scale, 1671st of 4,698 Development & Engineering skills we index (top 36%).
Its SKILL.md is 14 KB long, well organised into 35 sections with 13 code examples: a thorough specification that gives an agent plenty to work with.
With 1,143 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-10-31 found the source still online.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 86/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
debugging-instruments compared with similar skills
All 4 of these similar skills score higher than debugging-instruments; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| debugging-instruments (this skill)by dpearson2699 | 89 | 1.1k | 4mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install debugging-instruments?
- Run
npx skills add dpearson2699/swift-ios-skills --skill debugging-instruments. The install tabs above show the steps for each supported agent. - Which AI agents does debugging-instruments work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is debugging-instruments safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 86/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is debugging-instruments still maintained?
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: debugging-instruments description: "Debug iOS apps and profile performance using LLDB, the interactive Memory Graph Debugger, and Instruments. Use for crashes, retain-cycle inspection, hangs, build failures, and generic CPU, memory, energy, or network profiling. Use ios-memgraph-analysis for .memgraph capture, leaks CLI ownership paths, or persistent heap growth; use ios-ettrace-performance for ETTrace capture and JSON."
Debugging and Instruments
Keep interactive graph and Instruments triage here. Route detailed .memgraph
command-line ownership/growth analysis and ETTrace work to their focused skills.
Contents
- LLDB Debugging
- Memory Debugging
- Hang Diagnostics
- Build Failure Triage
- Instruments Overview
- Common Mistakes
- Review Checklist
- References
LLDB Debugging
Start with a small, repeatable workflow:
- Reproduce in a Debug build and stop at the narrowest useful breakpoint.
- Inspect locals without executing code, then capture the current stack.
- Move to the relevant frame or thread and verify the failing state.
- Add a condition or watchpoint only when the bad transition is still unclear.
(lldb) br set -f ViewModel.swift -l 42 # Stop at file and line
(lldb) v myLocal # Inspect without executing code
(lldb) po myObject # Use debugDescription when needed
(lldb) bt all # Capture every thread's backtrace
(lldb) frame select 3 # Inspect a relevant frame
(lldb) br modify 1 -c "count > 10" # Narrow a noisy breakpoint
(lldb) w set v self.score # Stop on an unexpected write
Use v over po when you only need a local variable value — it does not
execute code and cannot trigger side effects. Expression evaluation can execute
or mutate program state, and hardware watchpoints are scarce, so use both
deliberately.
Load references/lldb-patterns.md for the complete inspection, breakpoint/logpoint, expression, watchpoint, thread navigation, and symbolic-breakpoint command tables.
Memory Debugging
Memory Graph Debugger Workflow
- Run the app in Debug configuration.
- Reproduce the suspected leak (navigate to a screen, then back).
- Tap the Memory Graph button in Xcode's debug bar.
- Look for purple warning icons — these indicate leaked objects.
- Select a leaked object to see its reference graph and backtrace.
Enable Malloc Stack Logging (Scheme > Diagnostics) before running so the Memory Graph shows allocation backtraces.
Common Retain Cycle Patterns
Closure capturing self strongly:
// LEAK — closure holds strong reference to self
class ProfileViewModel {
var onUpdate: (() -> Void)?
func startObserving() {
onUpdate = {
self.refresh() // strong capture of self
}
}
}
// FIXED — use [weak self]
func startObserving() {
onUpdate = { [weak self] in
self?.refresh()
}
}
Strong delegate reference:
// LEAK — strong delegate creates a cycle
protocol DataDelegate: AnyObject {
func didUpdate()
}
class DataManager {
var delegate: DataDelegate? // should be weak
}
// FIXED — weak delegate
class DataManager {
weak var delegate: DataDelegate?
}
Timer retaining target:
// LEAK — Timer.scheduledTimer retains its target
timer = Timer.scheduledTimer(
timeInterval: 1.0, target: self,
selector: #selector(tick), userInfo: nil, repeats: true
)
// FIXED — use closure-based API with [weak self]
timer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { [weak self] _ in
self?.tick()
}
Instruments: Allocations and Leaks
- Allocations template: Track memory growth over time. Use the "Mark Generation" feature to isolate allocations created between user actions (e.g., open/close a screen).
- Leaks template: Detects leaked allocations, including isolated retain cycles the process can no longer reach. Run alongside Allocations for a complete picture.
- Filter by your app's module name to exclude system allocations.
For leak or memory-growth triage, pair the tools: use Allocations Mark Generation before and after the reproduction step to prove retained growth, then use Memory Graph Debugger to inspect object ownership and Malloc Stack Logging to recover allocation call stacks.
Malloc Stack Logging
Enable in Scheme > Run > Diagnostics > Malloc Stack Logging. This records
allocation backtraces so the Memory Graph Debugger, Allocations instrument,
and exported .memgraph files can show where objects were created.
# Inspect an exported memory graph from Xcode or Instruments
leaks MyApp.memgraph
Hang Diagnostics
Identifying Main Thread Hangs
For discrete interactions, delays under 100 ms are rarely noticeable. Apple developer tools commonly report main-run-loop busy periods over 250 ms, but that reporting threshold is not a product target: a few hundred milliseconds can still feel unresponsive. Common detection tools:
- Thread Checker (Xcode Diagnostics): warns about non-main-thread UI calls
- Thread Performance Checker: reports priority inversions while debugging
- On-device Hang Detection: Developer Settings reports hangs from device use
- Time Profiler / CPU Profiler / Hitches: profile reproducible hangs
- os_signpost and
OSSignposter: mark intervals for Instruments - MetricKit hang diagnostics: production hang detection (see
metrickitskill forHangDiagnosticand iOS 26 compatibility)
import os
let signposter = OSSignposter(subsystem: "com.example.app", category: "DataLoad")
func loadData() async {
let state = signposter.beginInterval("loadData")
let result = await fetchFromNetwork()
signposter.endInterval("loadData", state)
process(result)
}
Using the Time Profiler
- Product > Profile (Cmd+I) to launch Instruments.
- Select the Time Profiler template.
- Record while reproducing the slow interaction.
- Focus on the main thread — sort by "Weight" to find hot paths.
- Check "Hide System Libraries" to see only your code.
- Double-click a heavy frame to jump to source.
Common Hang Causes
| Cause | Symptom | Fix |
|-------|---------|-----|
| Synchronous I/O on main thread | Network/file reads block UI | Move to Task { } or background actor |
| Lock contention | Main thread waiting on a lock held by background work | Use actors or reduce lock scope |
| Layout thrashing | Repeated layoutSubviews calls | Batch layout changes, avoid forced layout |
| JSON parsing large payloads | UI freezes during data load | Parse on a background thread |
| Synchronous image decoding | Scroll jank on image-heavy lists | Use AsyncImage or decode off main thread |
Build Failure Triage
Reading Compiler Diagnostics
- Start from the first error — subsequent errors are often cascading.
- Search for the error code (e.g.,
error: cannot convert) in the build log. - Use Report Navigator (Cmd+9) for the full build log with timestamps.
SPM Dependency Resolution
# Common: version conflict
error: Dependencies could not be resolved because root depends on 'Package' 1.0.0..<2.0.0
# Fix: check Package.resolved and update version ranges
# Reset package caches if needed:
rm -rf ~/Library/Caches/org.swift.swiftpm
rm -rf .build
swift package resolve
Module Not Found / Linker Errors
| Error | Check |
|-------|-------|
| No such module 'Foo' | Target membership, import paths, framework search paths |
| Undefined symbol | Linking phase missing framework, wrong architecture |
| duplicate symbol | Two targets define same symbol; check for ObjC naming collisions |
Build settings to inspect first:
FRAMEWORK_SEARCH_PATHSOTHER_LDFLAGSSWIFT_INCLUDE_PATHSBUILD_LIBRARY_FOR_DISTRIBUTION(for XCFrameworks)
Instruments Overview
Template Selection Guide
| Template | Use When | |----------|----------| | Time Profiler | CPU is high, UI feels slow, need to find hot code paths | | Allocations | Memory grows over time, need to track object lifetimes | | Leaks | Suspect retain cycles or abandoned objects | | Network | Inspecting HTTP request/response timing and payloads | | SwiftUI | Profiling view body evaluations and update frequency | | Animation Hitches / Core Animation instruments | Frame drops, hitches, blending, and commit/render work | | Power Profiler | Battery drain, thermal pressure, background energy impact | | File Activity | Excessive disk I/O, slow file operations | | System Trace | Thread scheduling, syscalls, virtual memory faults |
xctrace CLI for CI Profiling
# Record a trace from the command line
xcrun xctrace record --device "My iPhone" \
--template "Time Profiler" \
--instrument "Allocations" \
--output profile.trace \
--launch -- /path/to/MyApp.app
# Export trace data as XML for automated analysis
xcrun xctrace export --input profile.trace --xpath '/trace-toc/run/data/table'
# List available templates
xcrun xctrace list templates
# List connected devices
xcrun xctrace list devices
Use one --template per recording; add extra instruments with
--instrument. Use xctrace in CI pipelines to catch performance regressions
automatically. Compare exported metrics between builds.
Common Mistakes
DON'T: Use print() for debugging instead of os.Logger
Use Logger for levels, privacy metadata, and subsystem/category filtering;
.debug remains in memory and is not persisted in release builds.
// WRONG — unstructured and not filterable by subsystem/category
print("user tapped button, state: \(viewModel.state)")
print("network response: \(data)")
// CORRECT — structured logging with Logger
import os
let logger = Logger(subsystem: "com.example.app", category: "UI")
logger.debug("Button tapped, state: \(viewModel.state, privacy: .public)")
logger.info("Network response received, bytes: \(data.count)")
DON'T: Forget to enable Malloc Stack Logging before memory debugging
// WRONG — open Memory Graph without enabling Malloc Stack Logging
// Result: leaked objects visible but no allocation backtrace
// CORRECT — enable BEFORE running:
// Scheme > Run > Diagnostics > check "Malloc Stack Logging: All Allocations"
// Then run, reproduce the leak, and open Memory Graph
DON'T: Debug optimized code expecting full variable visibility
// WRONG — profiling with Debug build, debugging with Release build
// Debug builds: extra runtime checks distort perf measurements
// Release builds: variables show as "<optimized out>" in debugger
// CORRECT approach:
// Debugging: use Debug configuration (full symbols, no optimization)
// Profiling: use Release configuration (realistic performance)
DON'T: Stop on every loop iteration without conditional breakpoints
// WRONG — breakpoint on line inside loop, stops 10,000 times
for item in items {
process(item) // breakpoint here stops on EVERY item
}
// CORRECT — use a conditional breakpoint:
// (lldb) br set -f MyFile.swift -l 42 -c "item.id == targetID"
// Or in Xcode: right-click breakpoint > Edit > add Condition
DON'T: Ignore Thread Sanitizer warnings
Thread Sanitizer (TSan) warnings indicate data races that may only crash intermittently. Treat them as real bugs unless you have isolated a tool issue.
// WRONG — ignoring TSan warning about concurrent access
var cache: [String: Data] = [:] // accessed from multiple threads
// CORRECT — protect shared mutable state
actor CacheActor {
var cache: [String: Data] = [:]
func get(_ key: String) -> Data? { cache[key] }
func set(_ ke
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
