SkillAgentSearch skills...

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-instruments

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

89/100

Supported Platforms

Universal

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.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
13/20
Freshness
11/15

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 found

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.

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.

SkillScoreStarsUpdatedFormat
debugging-instruments (this skill)by dpearson2699891.1k4mo agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
ai-job-searchby ai-job-search-dev10072.1ktodayCLAUDE.md
claude-howtoby luongnv8910047.3k2d agoCLAUDE.md
lobehubby lobehub10085.6ktodayMCP 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.

name: 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

Start with a small, repeatable workflow:

  1. Reproduce in a Debug build and stop at the narrowest useful breakpoint.
  2. Inspect locals without executing code, then capture the current stack.
  3. Move to the relevant frame or thread and verify the failing state.
  4. 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

  1. Run the app in Debug configuration.
  2. Reproduce the suspected leak (navigate to a screen, then back).
  3. Tap the Memory Graph button in Xcode's debug bar.
  4. Look for purple warning icons — these indicate leaked objects.
  5. 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 metrickit skill for HangDiagnostic and 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

  1. Product > Profile (Cmd+I) to launch Instruments.
  2. Select the Time Profiler template.
  3. Record while reproducing the slow interaction.
  4. Focus on the main thread — sort by "Weight" to find hot paths.
  5. Check "Hide System Libraries" to see only your code.
  6. 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_PATHS
  • OTHER_LDFLAGS
  • SWIFT_INCLUDE_PATHS
  • BUILD_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

View on GitHub
GitHub Stars1.1k
CategoryDevelopment
Updated3mo ago
Forks58

Languages

Python

Trust signals

86/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium1 info