AX

A diagnostic guide for resolving iOS build and environment failures.

Install

mkdir -p .claude/skills/axiom-ios-build && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/2896" && unzip -o skill.zip -d .claude/skills/axiom-ios-build && rm skill.zip

Installs to .claude/skills/axiom-ios-build

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

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.
228 chars✓ has a “when” trigger
Advanced

Key capabilities

  • →Diagnose Xcode build failures
  • →Resolve dependency conflicts in CocoaPods and SPM
  • →Analyze simulator and test crashes
  • →Optimize build performance
  • →Audit security and privacy configurations

How it works

The agent routes issues to specialized sub-skills for environment diagnostics, dependency resolution, or crash analysis before suggesting code changes.

Inputs & outputs

You give it
Build error log or crash report
You get back
Diagnostic report and remediation steps

When to use axiom-ios-build

  • →Debug Xcode build failure
  • →Fix dependency linkage issues
  • →Resolve test crashes in simulator

About this skill

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:

"$AXBUILD" xcodebuild -scheme "$SCHEME" -destination "$DESTINATION" build
"$AXBUILD" swift test --package-path "$PACKAGE"

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, watchdo


Content truncated.

When not to use it

  • →When the issue is clearly a code-level logic bug
  • →When the environment is not an iOS/Xcode project

Prerequisites

Xcode project environmentAccess to build logs

Limitations

  • →Requires access to Xcode build environment
  • →Limited to iOS/Xcode-related issues

How it compares

It prioritizes environment-first diagnostics to resolve build and configuration issues before attempting code-level debugging.

Compared to similar skills

axiom-ios-build side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
axiom-ios-build (this skill)34moNo flagsAdvanced
flags510moNo flagsBeginner
vercel-advanced-troubleshooting34moCautionAdvanced
vercel-debug-bundle34moReviewBeginner

Try saying

Example prompts that trigger this skill in your AI assistant.

More by CharlesWiltgen

View all by CharlesWiltgen →

axiom-ios-accessibility

CharlesWiltgen

Use when fixing or auditing ANY accessibility issue - VoiceOver, Dynamic Type, color contrast, touch targets, WCAG compliance, App Store accessibility review.

13

axiom-ios-ai

CharlesWiltgen

Use when implementing ANY Apple Intelligence or on-device AI feature. Covers Foundation Models, @Generable, LanguageModelSession, structured output, Tool protocol, iOS 26 AI integration.

10

axiom-ios-data

CharlesWiltgen

Use when working with ANY data persistence, database, axiom-storage, CloudKit, migration, or serialization. Covers SwiftData, Core Data, GRDB, SQLite, CloudKit sync, file storage, Codable, migrations.

10

axiom-ios-performance

CharlesWiltgen

Use when app feels slow, memory grows, battery drains, or diagnosing ANY performance issue. Covers memory leaks, profiling, Instruments workflows, retain cycles, performance optimization.

11

axiom-networking

CharlesWiltgen

Use when implementing Network.framework connections, debugging connection failures, migrating from sockets/URLSession streams, or adopting structured concurrency networking patterns - prevents deprecated API usage, reachability anti-patterns, and thread-safety violations with iOS 12-26+ APIs

11

axiom-vision

CharlesWiltgen

subject segmentation, VNGenerateForegroundInstanceMaskRequest, isolate object from hand, VisionKit subject lifting, image foreground detection, instance masks, class-agnostic segmentation, VNRecognizeTextRequest, OCR, VNDetectBarcodesRequest, DataScannerViewController, document scanning, RecognizeDocumentsRequest

01

You might also like

flags

facebook

Use when you need to check feature flag states, compare channels, or debug why a feature behaves differently across release channels.

530

vercel-advanced-troubleshooting

jeremylongshore

Execute apply Vercel advanced debugging techniques for hard-to-diagnose issues. Use when standard troubleshooting fails, investigating complex race conditions, or preparing evidence bundles for Vercel support escalation. Trigger with phrases like "vercel hard bug", "vercel mystery error", "vercel impossible to debug", "difficult vercel issue", "vercel deep debug".

320

vercel-debug-bundle

jeremylongshore

Execute collect Vercel debug evidence for support tickets and troubleshooting. Use when encountering persistent issues, preparing support tickets, or collecting diagnostic information for Vercel problems. Trigger with phrases like "vercel debug", "vercel support bundle", "collect vercel logs", "vercel diagnostic".

318

stac-troubleshooter

StacDev

Diagnose Stac build, deploy, rendering, caching, and navigation issues using repeatable checks. Use when users report stac build finding no screens, deploy mismatches, runtime unknown widget/action errors, cache staleness, or migration regressions.

13

replit-incident-runbook

jeremylongshore

Execute Replit incident response procedures with triage, mitigation, and postmortem. Use when responding to Replit-related outages, investigating errors, or running post-incident reviews for Replit integration failures. Trigger with phrases like "replit incident", "replit outage", "replit down", "replit on-call", "replit emergency", "replit broken".

00

electron-pro

jshsakura

Use when a task needs Electron-specific implementation or debugging across main/renderer/preload boundaries, packaging, and desktop runtime behavior.

00

Search skills

Search the agent skills registry