Symbolicate .NET runtime frames in Apple platform .ips crash logs (iOS, tvOS, Mac Catalyst, macOS). Extracts UUIDs and addresses from the native backtrace, locates dSYM debug symbols, and runs atos to
Install
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add dotnet/skills --skill apple-crash-symbolication -a cursor -y
Symbolicate .NET runtime frames in Apple platform .ips crash logs (iOS, tvOS, Mac Catalyst, macOS). Extracts UUIDs and addresses from the native backtrace, locates dSYM debug symbols, and runs atos to produce function names with source file and line numbers. Automatically downloads .dwarf symbols from the Microsoft symbol server using Mach-O UUIDs. USE FOR triaging a .NET MAUI or Mono app crash from an .ips file on any Apple platform, resolving native backtrace frames in libcoreclr or libmonosgen-2.0 to .NET runtime source code, retrieving .ips crash logs from a connected iOS device or iPhone, or investigating EXC_CRASH, EXC_BAD_ACCESS, SIGABRT, or SIGSEGV originating from the .NET runtime. DO NOT USE FOR pure Swift/Objective-C crashes with no .NET components, or Android tombstone files. INVOKES Symbolicate-Crash.ps1 script, atos, dwarfdump, idevicecrashreport.
name: apple-crash-symbolication
description: Symbolicate .NET runtime frames in Apple platform .ips crash logs (iOS, tvOS, Mac Catalyst, macOS). Extracts UUIDs and addresses from the native backtrace, locates dSYM debug symbols, and runs atos to produce function names with source file and line numbers. Automatically downloads .dwarf symbols from the Microsoft symbol server using Mach-O UUIDs. USE FOR triaging a .NET MAUI or Mono app crash from an .ips file on any Apple platform, resolving native backtrace frames in libcoreclr or libmonosgen-2.0 to .NET runtime source code, retrieving .ips crash logs from a connected iOS device or iPhone, or investigating EXC_CRASH, EXC_BAD_ACCESS, SIGABRT, or SIGSEGV originating from the .NET runtime. DO NOT USE FOR pure Swift/Objective-C crashes with no .NET components, or Android tombstone files. INVOKES Symbolicate-Crash.ps1 script, atos, dwarfdump, idevicecrashreport.
license: MIT
Apple Platform Crash Log .NET Symbolication
Resolves native backtrace frames from .NET MAUI and Mono app crashes on Apple platforms (iOS, tvOS, Mac Catalyst, macOS) to function names, source files, and line numbers using Mach-O UUIDs and dSYM debug symbol bundles.
Inputs: Crash log file (.ips JSON format, iOS 15+ / macOS 12+), atos (from Xcode), optionally a connected iOS device to pull crash logs from.
Do not use when: The crashing library is not a .NET component (e.g., pure Swift/UIKit), or the crash log is an Android tombstone.
Workflow
Step 1: Parse the .ips Crash Log
Format check: Before proceeding, verify the file is .ips JSON format. The first line must be valid JSON. If the file is plain text (e.g., Android tombstone with #NN pc frame lines, or legacy Apple .crash text format), stop immediately — this workflow does not apply. Report the format mismatch to the user and do not attempt any symbolication.
The .ips file is two-part JSON: line 1 is a metadata header; the remaining lines are a separate JSON crash body. Parse them separately:
asi (Application Specific Information) often contains the managed exception message
lastExceptionBacktrace has frames from the exception that triggered the crash
faultingThread is the index into the threads array
Parsing gotcha: Some .ips files have case-conflicting duplicate keys (vmRegionInfo / vmregioninfo). Pre-process the raw JSON to rename the lowercase duplicate before parsing. The asi field may be absent.
Step 2: Identify .NET Runtime Libraries
Filter usedImages to .NET runtime libraries:
Library
Runtime
libcoreclr
CoreCLR runtime
libmonosgen-2.0
Mono runtime
libSystem.Native
.NET BCL native component
libSystem.Globalization.Native
.NET BCL globalization
libSystem.Security.Cryptography.Native.Apple
.NET BCL crypto
libSystem.IO.Compression.Native
.NET BCL compression
libSystem.Net.Security.Native
.NET BCL net security
On Apple platforms these ship as .framework bundles, so image names may omit .dylib. Match using substring (e.g., libcoreclr not libcoreclr.dylib). The app binary may appear twice in usedImages with different UUIDs.
Key bridge functions in the app binary: xamarin_process_managed_exception (managed exception bridged to ObjC NSException), xamarin_main, mono_jit_exec, coreclr_execute_assembly.
NativeAOT: Runtime is statically linked into the app binary. libSystem.* BCL libraries remain separate. The app binary needs its own dSYM from the build output.
Skip libsystem_kernel.dylib, UIKitCore, and other Apple system frameworks unless specifically asked.
Step 3: Interpret the Crash
Start with asi (Application Specific Information) — for .NET crashes, it often contains the managed exception type and message (e.g., XamlParseException, NullReferenceException). The root cause may already be visible here.
Then examine the faulting thread (threads[faultingThread]). Explain what frames #0 and #1 mean before examining other threads. Cross-thread context (GC state, thread pool) is useful for validation but not evidence of causation.
Also check lastExceptionBacktrace for the managed exception path through bridge functions like xamarin_process_managed_exception.
Sometimes the .NET runtime version is visible in image paths in usedImages, particularly on macOS when using shared-framework installs or NuGet-pack-style layouts (e.g., .../Microsoft.NETCore.App/10.0.4/libcoreclr.dylib). On iOS, however, image paths are typically inside the app bundle (for example, .../Frameworks/libcoreclr.framework/libcoreclr) and do not embed the runtime version, so you usually need to infer it via the Mach-O UUID by matching against SDK packs or symbol-server downloads rather than relying on the path alone.
Step 4: Locate dSYMs
For each .NET library needing symbolication, locate a UUID-matched dSYM:
Microsoft symbol server (automatic): Download .dwarf via https://msdl.microsoft.com/download/symbols/_.dwarf/mach-uuid-sym-{UUID}/_.dwarf (UUID lowercase, no dashes). Convert to .dSYM bundle (use the image name from usedImages[].name, e.g., libcoreclr):
Strip the /__w/1/s/ CI workspace prefix from output — meaningful paths start at src/runtime/, mapping to the dotnet/dotnet VMR.
Automation Script
scripts/Symbolicate-Crash.ps1 automates the full workflow (parsing, dSYM lookup, symbol download, and symbolication). Resolve the path relative to this SKILL.md file.
# $SKILL_DIR is the directory containing this SKILL.md
pwsh "$SKILL_DIR/scripts/Symbolicate-Crash.ps1" -CrashFile MyApp-2026-02-25.ips
Start with -ParseOnly for a fast overview without requiring atos. The script automatically downloads symbols from the Microsoft symbol server when local dSYMs are missing.
Also available in Xcode > Window > Devices and Simulators > View Device Logs, or at ~/Library/Logs/CrashReporter/ (Mac Catalyst), ~/Library/Logs/DiagnosticReports/ (macOS).
Validation
dwarfdump --uuid <dsym> matches UUID from the crash log
At least one .NET frame resolves to a function name (not a raw address)
Wrong file format: If the file is not .ips JSON (e.g., Android tombstone with #NN pc stack frames, legacy .crash text format), stop immediately — report the format mismatch to the user and do not proceed with any symbolication. Do not attempt to symbolicate using other tools or workflows.
No .NET frames found: Report parsed frames and stop.
All frames resolved: Present symbolicated backtrace with brief crash analysis (faulting thread, exception type, likely area). If the user asks for deeper investigation, proceed.
dSYM not available / UUID mismatch: Report unsymbolicated frames with UUIDs and addresses. Suggest locating the original build artifacts.
atos not available: Present the manual atos commands for the user to run. Do not install Xcode. atos ships with Xcode Command Line Tools (xcode-select --install).
References
IPS format details: See references/ips-crash-format.md for additional .ips parsing details and macOS symbol package differences.
How do I install apple-crash-symbolication?
Download plugins/dotnet-diag/skills/apple-crash-symbolication/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does apple-crash-symbolication live?
The publisher keeps it at https://github.com/dotnet/skills.
Which agents can use apple-crash-symbolication?
Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.