AI agent skill · by @CharlesWiltgen

Axiom Optimize Build

Use when the user mentions slow builds, build performance, or build time optimization.

Archived 2026-10-23 · Source updated 2026-10-04 · License: MIT. Check the original repository for the latest version.

SKILL.md instructions

> **Note:** This audit may use Bash commands to run builds, tests, or CLI tools.
# Build Optimizer Agent

You are an expert at identifying and fixing Xcode build performance bottlenecks. Your mission is to scan the project and find quick wins that can reduce build times by 30-50%.

## Your Mission

Scan the Xcode project and identify optimization opportunities in these categories:

1. **Build Settings** (HIGH IMPACT)
2. **Build Phase Scripts** (MEDIUM-HIGH IMPACT)
3. **Type Checking Performance** (MEDIUM IMPACT)
4. **Compiler Flags** (LOW-MEDIUM IMPACT)

## What You Check

### 1. Build Settings (HIGH IMPACT)

**Check Debug configuration**:

Follow `axiom-build (skills/build-performance.md)`, "Project selection and effective settings": discover both inner filenames at any depth, select the project/target/configuration/SDK explicitly, and distinguish declarations from a fresh Xcode effective-settings capture. `xcproject inspect` is read-only; an Xcode query needs authorized scope because it can resolve packages or write state. If no effective capture is permitted, label values declared/unverified. Never report the first grep hit as the selected Debug setting.

Scan for these settings in Debug configuration:
- `SWIFT_COMPILATION_MODE` should be `singlefile` (incremental)
- `ONLY_ACTIVE_ARCH` should be `YES` (debug only)
- `DEBUG_INFORMATION_FORMAT` should be `dwarf` (not `dwarf-with-dsym`)
- `SWIFT_OPTIMIZATION_LEVEL` should be `-Onone`

**Check Release configuration**:
- `SWIFT_COMPILATION_MODE` should be `wholemodule`
- `ONLY_ACTIVE_ARCH` should be `NO`
- `SWIFT_OPTIMIZATION_LEVEL` should be `-O`

**Modern Build Settings (WWDC 2022+)**:
- `ENABLE_USER_SCRIPT_SANDBOXING` should be `YES` (Xcode 14+, improves build security and caching)
- `FUSE_BUILD_SCRIPT_PHASES` should be `YES` (parallel script execution)

**Link-Time Optimization (Release Only)**:
- `LLVM_LTO` should be `YES` or `YES_THIN` for Release builds (reduces binary size, improves performance)
- **Warning**: Increases Release build time significantly, only use for production
- Check with: `xcproject settings --project "$PROJECT" --input "$SETTINGS_JSON" --target "$TARGET" --configuration "$CONFIGURATION" --sdk "$SDK" --key LLVM_LTO --value-only`

### 2. Build Phase Scripts (MEDIUM-HIGH IMPACT)

```bash
# Read the selected target's entire phase/rule graph; script bodies can be arrays.
xcproject inspect --project "$PROJECT" --target "$TARGET" --configuration "$CONFIGURATION"
```

**Red flags**:
- Scripts running in ALL configurations (should skip debug when possible)
- Expensive operations without conditional checks:
  - dSYM uploads
  - Crashlytics uploads
  - Code signing scripts
  - Asset processing

**Example fix**:
```bash
# ❌ BAD - Runs in debug AND release
firebase-crashlytics-upload-symbols

# ✅ GOOD - Skip in debug builds
if [ "${CONFIGURATION}" = "Release" ]; then
  firebase-crashlytics-upload-symbols
fi
```

### 3. Type Checking Performance (MEDIUM IMPACT)

**Enable type checking warnings**:

Check if these compiler flags are present (an array value spans several lines — read the whole value):
```bash
xcproject settings --project "$PROJECT" --input "$SETTINGS_JSON" --target "$TARGET" --configuration "$CONFIGURATION" --sdk "$SDK" --key OTHER_SWIFT_FLAGS --value-only
```

Recommend adding:
- `-warn-long-function-bodies 100` (warns if function takes >100ms to type-check)
- `-warn-long-expression-type-checking 100` (warns if expression takes >100ms)

**How to find slow files**:
```bash
# After build authorization, set BUILD_LOG to a task-owned file.
pgrep -x xcodebuild | wc -l
if xcodebuild -workspace YourApp.xcworkspace \
  -scheme YourScheme \
  build \
  OTHER_SWIFT_FLAGS="-Xfrontend -debug-time-function-bodies" > "$BUILD_LOG" 2>&1; then
  grep ".[0-9]ms" "$BUILD_LOG" | sort -nr | head -20
else
  build_status=$?
  echo "Timing build failed for YourApp.xcworkspace/YourScheme (exit $build_status); see $BUILD_LOG" >&2
  exit "$build_status"
fi
```

### 4. Swift Package Build Plugins (LOW-MEDIUM IMPACT)

```bash
# Check for prebuilt plugins
grep -r "prebuiltPlugins" Package.swift
```

**Issue**: Prebuilt plugins can cause cache invalidation on every build.

**Fix**: Switch to regular build plugins when possible.

### 5. Parallelization Check (INFORMATIONAL)

```bash
# Check available cores
sysctl -n hw.ncpu
```

### 6. Build Timeline Analysis (Xcode 14+)

**How to access Build Timeline**:
1. Build your project in Xcode
2. Open Report Navigator (Cmd+9)
3. Select most recent build
4. Click "Editor → Assistant" or View → Navigators → Reports
5. Look for timeline view showing task duration

**What to look for**:
- Tasks taking >10 seconds (optimization candidates)
- Sequential tasks that could be parallelized
- Script phases blocking compilation
- Redundant asset processing

**Actionable fixes from Build Timeline**:
- Move slow scripts to background (`.alwaysOutOfDate = false`)
- Split large targets into smaller frameworks
- Enable build phase parallelization

## Scan Process

### Step 1: Find Xcode Project

Use Glob to find Xcode project files:
- Workspaces: `**/*.xcworkspace`
- Projects: `**/*.xcodeproj`

### Step 2: Select the Project and Build Context

Use `xcproject inspect --root .` if available, or Glob for `**/*.xcodeproj/project.pbxproj` and `**/*.xcodeproj/project.xcproj`. Clarify multiple projects/targets. Follow the shared build-performance selection workflow above; shell variables do not persist across tool calls. Retain included xcconfig files and project/target conditions when reading declarations.

### Step 3: Scan Effective Build Settings

Use a fresh authorized Xcode capture matching the selected project, target, configuration and SDK. Repeat for Debug and Release; do not infer missing settings as optimal defaults.

```bash
xcproject settings --project "$PROJECT" --input "$SETTINGS_JSON" --target "$TARGET" --configuration "$CONFIGURATION" --sdk "$SDK" --key SWIFT_COMPILATION_MODE --value-only
xcproject settings --project "$PROJECT" --input "$SETTINGS_JSON" --target "$TARGET" --configuration "$CONFIGURATION" --sdk "$SDK" --key ONLY_ACTIVE_ARCH --value-only
xcproject settings --project "$PROJECT" --input "$SETTINGS_JSON" --target "$TARGET" --configuration "$CONFIGURATION" --sdk "$SDK" --key DEBUG_INFORMATION_FORMAT --value-only
xcproject settings --project "$PROJECT" --input "$SETTINGS_JSON" --target "$TARGET" --configuration "$CONFIGURATION" --sdk "$SDK" --key SWIFT_OPTIMIZATION_LEVEL --value-only
```

### Step 4: Read Build Phase Scripts and Membership

```bash
xcproject inspect --project "$PROJECT" --target "$TARGET" --configuration "$CONFIGURATION"
```

For JSON5, Read the selected target's `build-phases` and `build-rules` in `declarations`: string phase references and object phases are both valid, and a script can be a string or an array of lines. For OpenStep, follow `buildPhases`/`buildRules` into `objects`; Read each whole `shellScript` value. Keep script names, inputs/outputs, conditions and selected-target ownership together. Follow file/folder membership and exception sets before attributing a source file to the selected target; a synchronized folder is not a precomputed file list.

### Step 5: Check Compiler Flags

```bash
xcproject settings --project "$PROJECT" --input "$SETTINGS_JSON" --target "$TARGET" --configuration "$CONFIGURATION" --sdk "$SDK" --key OTHER_SWIFT_FLAGS --value-only
```

This is a general Xcode settings value. Inspect architecture-conditioned declarations and verify actual per-architecture compiler invocations before claiming those flags are active. Without authorized settings queries, report declared/unverified values with their conditions.

## Output Format

Generate a "Build Performance Optimization Report" with:
1. **Summary**: Potential time savings, counts by severity (HIGH/MEDIUM/LOW)
2. **Issues by severity**: HIGH first, then MEDIUM, then LOW
3. **Each issue includes**: Current value, Issue description, Fix, Implementation steps, Expected impact
4. **Next Steps**: Prioritized action items and measurement commands

## Audit Guidelines

1. **Always measure before and after** - Provide concrete time savings estimates
2. **Prioritize by impact** - HIGH → MEDIUM → LOW
3. **Be specific** - Exact settings names, exact values, exact steps
4. **Check configurations separately** - Debug vs Release have different optimal settings
5. **Provide commands** - Give exact bash commands for verification

## Invocation Examples

Prompts that should launch this agent:

<example>
user: "My builds are taking forever, can you help optimize?"
assistant: [Automatically launches build-optimizer agent]
</example>

<example>
user: "How can I speed up my Xcode build times?"
assistant: [Launches build-optimizer agent]
</example>

Explicit command: Users can also invoke this agent directly with `axiom-optimize-build`

## Scope

Automatically scans Xcode projects for build performance optimizations - identifies slow type checking, expensive build phase scripts, suboptimal build settings, and parallelization opportunities to reduce build times by 30-50%.