Xcode Build Benchmark
Record reproducible Xcode clean and incremental build benchmarks under `.build-benchmark/` so you can compare wall-clock regressions before shipping iOS updates.
Overview
xcode-build-benchmark is an agent skill most often used in Ship (also Build) that standardizes Xcode build benchmark artifacts and wall-clock versus timing-summary interpretation.
Install
npx skills add https://github.com/avdlee/xcode-build-optimization-agent-skill --skill xcode-build-benchmarkWhat is this skill?
- Canonical `.build-benchmark/` layout for JSON summaries and per-run Xcode logs
- Wall-clock `duration_seconds` and `median_seconds` called out as the primary success metric
- Build Timing Summary categories documented as parallel cumulative work, not blocking proof alone
- Clean, multi-run clean, and compilation-cache log naming conventions for apples-to-apples compares
- Repeats clean-build logs across multiple numbered runs for median comparison
Adoption & trust: 2.3k installs on skills.sh; 1.1k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your agent reruns Xcode builds blindly because last week’s clean-build medians and logs are scattered or misread as cumulative task totals.
Who is it for?
Solo developers shipping Swift/iOS apps who iterate on compile time and want agent-assisted regression checks.
Skip if: Android Gradle workflows or teams that never profile Xcode wall-clock before release.
When should I use this skill?
You are measuring or comparing Xcode scheme build times and need a canonical `.build-benchmark/` artifact layout.
What do I get? / Deliverables
Repeated builds land in `.build-benchmark/` with JSON plus logs so the next optimization pass compares median wall-clock seconds with correct timing context.
- Timestamped benchmark JSON under `.build-benchmark/`
- Per-run clean and cached-clean Xcode build logs
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Build-time evidence belongs on the Ship shelf because it gates release confidence and perf tuning, even though you capture runs during Build. The skill defines measurement artifacts and timing interpretation for performance diagnosis, not feature implementation.
Where it fits
After splitting a Swift package, capture three clean runs so the agent sees if wall-clock median dropped.
Before tagging a release, compare new `.build-benchmark/` JSON against the last shipping tag.
Document macOS CI runner changes with the same log naming so remote builds match laptop evidence.
How it compares
Benchmark artifact discipline for Xcode logs—not a generic CI YAML generator or App Store Connect integration.
Common Questions / FAQ
Who is xcode-build-benchmark for?
Indie and small-team iOS builders using Claude Code or similar agents to track Xcode build performance with reproducible files.
When should I use xcode-build-benchmark?
In Build when restructuring modules and in Ship perf work before merging release branches, especially after enabling compilation cache or changing schemes.
Is xcode-build-benchmark safe to install?
It documents local log paths and build commands; check the Security Audits panel on this page and avoid committing secrets embedded in Xcode schemes.
SKILL.md
READMESKILL.md - Xcode Build Benchmark
# Benchmark Artifacts All skills in this repository should treat `.build-benchmark/` as the canonical location for measured build evidence. ## Goals - Keep build measurements reproducible. - Make clean and incremental build data easy to compare. - Preserve enough context for later specialist analysis without rerunning the benchmark. ## Wall-Clock vs Cumulative Task Time The `duration_seconds` field on each run and the `median_seconds` in the summary represent **wall-clock time** -- how long the developer actually waits. This is the primary success metric. The `timing_summary_categories` are **aggregated task times** parsed from Xcode's Build Timing Summary. Because Xcode runs many tasks in parallel across CPU cores, these totals typically exceed the wall-clock duration. A large cumulative `SwiftCompile` value is diagnostic evidence of compiler workload, not proof that compilation is blocking the build. Always compare category totals against the wall-clock median before concluding that a category is a bottleneck. ## File Layout Recommended outputs: - `.build-benchmark/<timestamp>-<scheme>.json` - `.build-benchmark/<timestamp>-<scheme>-clean-1.log` - `.build-benchmark/<timestamp>-<scheme>-clean-2.log` - `.build-benchmark/<timestamp>-<scheme>-clean-3.log` - `.build-benchmark/<timestamp>-<scheme>-cached-clean-1.log` (when COMPILATION_CACHE_ENABLE_CACHING is enabled) - `.build-benchmark/<timestamp>-<scheme>-cached-clean-2.log` - `.build-benchmark/<timestamp>-<scheme>-cached-clean-3.log` - `.build-benchmark/<timestamp>-<scheme>-incremental-1.log` - `.build-benchmark/<timestamp>-<scheme>-incremental-2.log` - `.build-benchmark/<timestamp>-<scheme>-incremental-3.log` Use an ISO-like UTC timestamp without spaces so the files sort naturally. ## Artifact Requirements Each JSON artifact should include: - schema version - creation timestamp - project context - environment details when available - the normalized build command - separate `clean` and `incremental` run arrays - summary statistics for each build type - parsed timing-summary categories - free-form notes for caveats or noise ## Clean, Cached Clean, And Incremental Separation Do not merge different build type measurements into a single list. They answer different questions: - **Clean builds** show full build-system, package, and module setup cost with a cold compilation cache. - **Cached clean builds** show clean build cost when the compilation cache is warm. This is the realistic scenario for branch switching, pulling changes, or Clean Build Folder. Only present when `COMPILATION_CACHE_ENABLE_CACHING = YES` is detected. - **Incremental builds** show edit-loop productivity and script or cache invalidation problems. ## Raw Logs Store raw `xcodebuild` output beside the JSON artifact whenever possible. That allows later skills to: - re-parse timing summaries - inspect failed builds - search for long type-check warnings - correlate build-system phases with recommendations ## Measurement Caveats ### COMPILATION_CACHE_ENABLE_CACHING `COMPILATION_CACHE_ENABLE_CACHING = YES` stores compiled artifacts in a system-managed cache outside DerivedData so that repeated compilations of identical inputs are served from cache. The standard clean-build benchmark (`xcodebuild clean` between runs) may add overhead from cache population without showing the corresponding cache-hit benefit. The benchmark script automatically detects `COMPILATION_CACHE_ENABLE_CACHING = YES` and runs a **cached clean** benchmark phase. This phase: 1. Builds once to warm the compilation cache. 2. Deletes DerivedData (but not the compilation cache) before each measured run. 3. Rebuilds, measuring the cache-hit clean build time. The cached clean metric captures the realistic developer experience: branch switching, pulling changes, and Clean Build Folder. Use the cached clean median as the primary comparison metric when evaluating `COMPILATION_CACHE_ENABLE_CACHING` impact. To skip this phase, pass `--n