🇺🇸English
iOS Build & Environment Router
You MUST use this skill for ANY build, environment, or Xcode-related issue before debugging application code.
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
Why xcode-debugging first : 90% of mysterious issues are environment, not code. Check this BEFORE debugging code.
Invoke : /skill axiom-xcode-debugging
2. Slow Builds → build-performance
Triggers :
- Compilation takes too long
- Type checking bottlenecks
- Want to optimize build time
- Build Timeline shows slow phases
Invoke : /skill axiom-build-performance
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 : /skill axiom-build-debugging
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 : /skill axiom-testflight-triage
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 : /skill axiom-app-store-connect-ref
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 : /skill axiom-metrickit-ref
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 : /skill axiom-hang-diagnostics
14. Live Debugging → axiom-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 axiom-lldb : Crash reports tell you WHAT crashed. LLDB tells you WHY.
Invoke : /skill axiom-lldb
Decision Tree
- Mysterious/intermittent/clean build fails? → xcode-debugging (environment-first)
- SPM dependency conflict? → spm-conflict-resolver (Agent)
- CocoaPods/other dependency conflict? → build-debugging
- Slow build time? → build-performance
- Security/privacy/App Store prep? → security-privacy-scanner (Agent)
- Want automated build fix (environment-first diagnostics)? → build-fixer (Agent)
- Want build time optimization scan? → build-optimizer (Agent)
- Modernization/deprecated APIs? → modernization-helper (Agent)
- TestFlight crash/feedback? → testflight-triage
- Navigating App Store Connect? → app-store-connect-ref
- Have a crash log (.ips/.crash)? → crash-analyzer (Agent)
- MetricKit setup/parsing? → metrickit-ref
- App hang/freeze/watchdog? → hang-diagnostics
- Need to reproduce crash interactively / inspect runtime state? → axiom-lldb
Anti-Rationalization
| Thought | Reality |
|---|
| "I know how to fix this linker error" | Linker errors have 4+ root causes. xcode-debugging diagnoses all in 2 min. |
| "Let me just clean the build folder" | Clean builds mask the real issue. xcode-debugging finds the root cause. |
| "It's just an SPM issue, I'll fix Package.swift" | SPM conflicts cascade. spm-conflict-resolver analyzes the full dependency graph. |
| "The simulator is just slow today" | Simulator issues indicate environment corruption. xcode-debugging checks systematically. |
| "I'll skip environment checks, it compiles locally" | Environment-first saves 30+ min. Every time. |
| "I'll read the crash report more carefully instead of reproducing" | Crash reports show WHAT crashed, not WHY. Reproducing in LLDB with breakpoints reveals the actual state. axiom-lldb has the workflow. |
When NOT to Use (Conflict Resolution)
Do NOT use ios-build for these — use the correct router instead:
| Error Type | Correct Router | Why NOT ios-build |
|---|
| Swift 6 concurrency errors | ios-concurrency | Code error, not environment |
| SwiftData migration errors | ios-data | Schema issue, not build environment |
| "Sending 'self' risks data race" | ios-concurrency | Language error, not Xcode issue |
| Type mismatch / compilation errors | Fix the code | These are code bugs |
ios-build is for environment mysteries , not code errors:
- ✅ "No such module" when code is correct
- ✅ Simulator won't boot
- ✅ Clean build fails, incremental works
- ✅ Zombie xcodebuild processes
- ❌ Swift concurrency warnings/errors
- ❌ Database migration failures
- ❌ Type checking errors in valid code
Example Invocations
User: "My build failed with a linker error" → Invoke: /skill axiom-xcode-debugging (environment-first diagnostic)
User: "Builds are taking 10 minutes" → Invoke: /skill axiom-build-performance
User: "SPM won't resolve dependencies" → Invoke: spm-conflict-resolver agent
User: "Two packages require different versions of the same dependency" → Invoke: spm-conflict-resolver agent
User: "Duplicate symbol linker error" → Invoke: spm-conflict-resolver agent
User: "I need to prepare for App Store security review" → Invoke: security-privacy-scanner agent
User: "Do I need a Privacy Manifest?" → Invoke: security-privacy-scanner agent
User: "Are there hardcoded credentials in my code?" → Invoke: security-privacy-scanner agent
User: "How do I migrate from ObservableObject to @Observable?" → Invoke: modernization-helper agent
User: "Update my code to use modern SwiftUI patterns" → Invoke: modernization-helper agent
User: "Should I still use @StateObject?" → Invoke: modernization-helper agent
User: "A beta tester said my app crashed" → Invoke: /skill axiom-testflight-triage
User: "I see crashes in App Store Connect but don't know how to investigate" → Invoke: /skill axiom-testflight-triage
User: "My crash logs aren't symbolicated" → Invoke: /skill axiom-testflight-triage
User: "I need to review TestFlight feedback" → Invoke: /skill axiom-testflight-triage
User: "How do I find crashes in App Store Connect?" → Invoke: /skill axiom-app-store-connect-ref
User: "Where's the crash-free users metric in ASC?" → Invoke: /skill axiom-app-store-connect-ref
User: "How do I export crash data from App Store Connect?" → Invoke: /skill axiom-app-store-connect-ref
User: "Analyze this crash log" [pastes .ips content] → Invoke: crash-analyzer agent or /axiom:analyze-crash
User: "Parse this .ips file: ~/Library/Logs/DiagnosticReports/MyApp.ips" → Invoke: crash-analyzer agent or /axiom:analyze-crash
User: "Why did my app crash? Here's the report..." → Invoke: crash-analyzer agent or /axiom:analyze-crash
User: "How do I set up MetricKit to collect crash data?" → Invoke: /skill axiom-metrickit-ref
User: "How do I parse MXDiagnosticPayload?" → Invoke: /skill axiom-metrickit-ref
User: "What's in MXCallStackTree and how do I decode it?" → Invoke: /skill axiom-metrickit-ref
User: "My app hangs sometimes" → Invoke: /skill axiom-hang-diagnostics
User: "The main thread is blocked and UI is unresponsive" → Invoke: /skill axiom-hang-diagnostics
User: "Xcode Organizer shows hang diagnostics for my app" → Invoke: /skill axiom-hang-diagnostics
User: "My app was killed by watchdog during launch" → Invoke: /skill axiom-hang-diagnostics
User: "I have a crash report and need to reproduce it in the debugger" → Invoke: /skill axiom-lldb
User: "How do I set breakpoints to catch this crash?" → Invoke: /skill axiom-lldb
User: "My build is failing with BUILD FAILED but no error details" → Invoke: build-fixer agent or /axiom:fix-build
User: "Build sometimes succeeds, sometimes fails" → Invoke: build-fixer agent or /axiom:fix-build
User: "How can I speed up my Xcode build times?" → Invoke: build-optimizer agent or /axiom:optimize-build
Weekly Installs
114
Repository
charleswiltgen/axiom
GitHub Stars
606
First Seen
Jan 21, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode97
codex92
gemini-cli89
claude-code88
github-copilot85
cursor85
