Use when ANY iOS build fails, test crashes, Xcode misbehaves, or environment issue occurs before debugging code. Covers build failures, compilation errors, dependency conflicts, simulator problems, environment-first diagnostics.

Build & Environment You MUST use this skill for ANY build, environment, or Xcode related issue before debugging application code. Bundled tools on Claude Code: if command v <tool finds nothing (hooks off or bare ), use <plugin root /tools/<tool in place of the bare name; <plugin root is two levels above this skill's Base directory for this skill: path. <! AXIOM AUDITOR INLINE BEGIN — auto maintained by scripts/build inlined auditors.ts; do not hand edit Can't launch Axiom agents? Where this router sends you to an agent, follow its procedure inline. Over MCP, axiom get agent returns it; elsewhere, read its file below, which needs only file search and read. Available here: skills/modernization helper.md . Homed in another suite: axiom security/skills/security privacy scanner.md . For any other agent, over MCP axiom get agent returns it too; run its xclog, xcsym and xcprof steps with the axiom xclog , axiom xcsym and axiom xcprof tools. Elsewhere, search Axiom's skills for skills/<agent .md ; if there is none, do that work yourself with this suite's skills, using any Axiom tool on your PATH . <! AXIOM AUDITOR INLINE END Capture Build and Test Diagnostics Before the next necessary build or test, resolve tools/axbuild under the actual loaded package in Claude Code ( command v axbuild ; if that finds nothing, tools/axbuild two levels above the Base directory for this skill: path of a loaded Axiom skill) or Codex ( <plugin root /tools/ ), or discover an executable on PATH in Pi. Check executable permission and run its absolute path with help ; assign that observed path to AXBUILD . Never infer an installation path from an example. Cursor and MCP distributions do not bundle axbuild and expose no axbuild MCP wrapper. Use the saved log fallback below when a verified shell helper is unavailable. Before every Xcode invocation, run pgrep lx xcodebuild; echo "pgrep exit=$?" : exit 1 means none are running, 0 lists them, and any other exit means the inventory failed. Investigate existing builds; process count and age do not establish zombie status. Never terminate unrelated processes. When interrupted or timed out, axbuild also stops build scripts and other processes descended from its build that Xcode moved into separate process groups, found by parentage when cleanup begins and on each cleanup pass. It reports cleanup incomplete for any such descendant it could not stop or verify (another user's, unreadable, or being debugged). Jobs that had already left the build's process tree, such as daemons or launchd started tools, are neither stopped nor reported. Inspect ownership before stopping anything it lists. Discover the actual scheme and destination before executing: Preserve caller flags, working directory, environment, test selection, coverage and explicit artifact paths. The wrapper adds absent diagnostic defaults; it never cleans caches or automatically rebuilds. Do not pipe a build through another command. Inspect command (native outcome) and collection (evidence completeness) separately. Native success can accompany partial collection. The default JSON is bounded to 8,000 UTF 8 bytes; inspect omissions and read artifacts.report relative to the absolute artifacts.run directory for complete records and evaluated values. The startup stderr JSON identifies the run directory before completion. Use diagnostic locations and values rather than rebuilding to redisplay output. The retained log is the primary compiler source; test results and validated Swift Testing events supplement it. A null failed test count means uncertainty, not zero. Preserve result bundles for attachment export, coverage, console logs and deeper inspection. Native informational commands pass their output through. Saved log fallback: redirect the necessary native command's stdout/stderr to a unique file, let it finish, record its exit status and inspect that saved file. An xcresult build summary is not equivalent to the compiler log. Read an existing log before considering another build. If a build's output ends in a truncation marker, or before xcodebuild's closing BUILD … or TEST … line, read the saved log or report instead of rebuilding. <! end of shared section; source: skills/axiom build/SKILL.md, copies regenerated by npm run build:shared When to Use Use this router when you encounter: Build failures ( BUILD FAILED , compilation errors, linker errors) Test crashes or hangs Simulator issues (won't boot, device errors) Xcode misbehavior (stale builds, zombie processes) Dependency conflicts (CocoaPods, SPM) Build performance issues (slow compilation) Environment issues before debugging code Routing Logic This router invokes specialized skills based on the specific issue: 1. Environment First Issues → xcode debugging Triggers : BUILD FAILED without obvious code cause Tests crash in clean project Simulator hangs or won't boot "No such module" after SPM changes Zombie xcodebuild processes Stale builds (old code still running) Clean build differs from incremental build Device Hub / predicted vs built issues in Xcode 27 ( OS27 ) Reproducing a device only bug on a simulator (Device Hub) ( OS27 ) Why xcode debugging first : 90% of mysterious issues are environment, not code. Check this BEFORE debugging code. Invoke : skills/xcode debugging.md 2. Slow Builds → build performance Triggers : Compilation takes too long Type checking bottlenecks Want to optimize build time Build Timeline shows slow phases Invoke : skills/build performance.md 3. SPM Dependency Conflicts → spm conflict resolver (Agent) Triggers : SPM resolution failures "No such module" after adding package Duplicate symbol linker errors Version conflicts between packages Swift 6 package compatibility issues Package.swift / Package.resolved conflicts Why spm conflict resolver : Specialized agent that analyzes Package.swift and Package.resolved to diagnose and resolve Swift Package Manager conflicts. Invoke : Launch spm conflict resolver agent 4. Security & Privacy Audit → security privacy scanner (Agent) Triggers : App Store submission prep Privacy Manifest requirements (iOS 17+) Hardcoded credentials in code Sensitive data storage concerns ATS violations Required Reason API declarations Why security privacy scanner : Specialized agent that scans for security vulnerabilities and privacy compliance issues. Invoke : Launch security privacy scanner agent or /axiom:audit security 5. iOS 17→18 Modernization → modernization helper (Agent) Triggers : Migrate ObservableObject to @Observable Update @StateObject to @State Adopt modern SwiftUI patterns Deprecated API cleanup iOS 17+ migration Why modernization helper : Specialized agent that scans for legacy patterns and provides migration paths with code examples. Invoke : Launch modernization helper agent or /axiom:audit modernization 6. Build Failure Auto Fix → build fixer (Agent) Triggers : BUILD FAILED with no clear error details Build sometimes succeeds, sometimes fails App builds but runs old code "Unable to boot simulator" error Want automated environment first diagnostics Why build fixer : Autonomous agent that checks zombie processes, Derived Data, SPM cache, and simulator state before investigating code. Saves 30+ minutes on environment issues. Invoke : Launch build fixer agent or /axiom:fix build 7. Slow Build Optimization → build optimizer (Agent) Triggers : Builds take too long Want to identify slow type checking Expensive build phase scripts Suboptimal build settings Want parallelization opportunities Why build optimizer : Scans Xcode projects for build performance optimizations — slow type checking, expensive scripts, suboptimal settings — to reduce build times by 30 50%. Invoke : Launch build optimizer agent or /axiom:optimize build 8. General Dependency Issues → build debugging Triggers : CocoaPods resolution failures "Multiple commands produce" errors Framework version mismatches Non SPM dependency graph conflicts Invoke : skills/build debugging.md 9. TestFlight Crash Triage → testflight triage Triggers : Beta tester reported a crash Crash reports in Xcode Organizer Crash logs aren't symbolicated TestFlight feedback with screenshots App was killed but no crash report Why testflight triage : Systematic workflow for investigating TestFlight crashes and reviewing beta feedback. Covers symbolication, crash interpretation, common patterns, and Claude assisted analysis. Invoke : See axiom shipping (skills/testflight triage.md) 10. App Store Connect Navigation → app store connect ref Triggers : How to find crashes in App Store Connect ASC metrics dashboard navigation Understanding crash free users percentage Comparing crash rates between versions Exporting crash data from ASC App Store Connect API for crash data Why app store connect ref : Reference for navigating ASC crash analysis, metrics dashboards, and data export workflows. Invoke : See axiom shipping (skills/app store connect ref.md) 11. Crash Log Analysis → crash analyzer (Agent) Triggers : User has .ips or .crash file to analyze User pasted crash report text Need to parse crash log programmatically Identify crash pattern from exception type Check symbolication status Why crash analyzer : Autonomous agent that parses crash reports, identifies patterns (null pointer, Swift runtime, watchdog, jetsam), and generates actionable analysis. Invoke : Launch crash analyzer agent or /axiom:analyze crash 12. MetricKit API Reference → metrickit ref Triggers : MetricKit setup and subscription MXMetricPayload parsing (CPU, memory, launches, hitches) MXDiagnosticPayload parsing (crashes, hangs, disk writes) MXCallStackTree decoding and symbolication Field crash/hang collection Background exit metrics Why metrickit ref : Complete MetricKit API reference with setup patterns, payload parsing, and integration with crash reporting systems. Invoke : See axiom performance ( skills/metrickit ref.md ) 13. Hang Diagnostics → hang diagnostics Triggers : App hangs or freezes Main thread blocked for 1 second UI unresponsive to touches Xcode Organizer shows hang diagnostics MXHangDiagnostic from MetricKit Watchdog terminations (app killed during launch/background transition) Why hang diagnostics : Systematic diagnosis of hangs with decision tree for busy vs blocked main thread, tool selection (Time Profiler, System Trace), and 8 common hang patterns with fixes. Invoke : See axiom performance ( skills/hang diagnostics.md ) 14. Live Debugging → lldb Triggers : Need to reproduce a crash interactively Want to set breakpoints and inspect state Crash report analyzed, now need live investigation Need to attach debugger to running app Why lldb : Crash reports tell you WHAT crashed. LLDB tells you WHY. Invoke : skills/lldb.md 16. Runtime Console Capture → xclog ref Triggers : Need to see what the app is logging at runtime App crashes but no crash report (need console output) Silent failures (network, data, auth) with no UI feedback Want to capture print()/os log() output from simulator Need structured log output for analysis "What is the app printing?" Why xclog ref : Xcode's debug console isn't accessible externally. xclog combines simctl stdout/stderr with log stream JSON to capture everything print(), NSLog(), os log(), and Logger emit — with structured fields (level, subsystem, category) for automated analysis. Invoke : /axiom:console 15. Code Signing Issues → code signing Triggers : "No signing certificate found" "Provisioning profile doesn't include signing

axiom-build