Benchmark Xcode clean, incremental, and zero-change builds to establish performance baselines and measure build duration overhead.
- GitHub stars
- 1,272
- Files
- 5
- Last commit
- Sep 14, 2026
- License
- MIT
- Allowed tools
- —
What does the xcode-build-benchmark skill do?
xcode-build-benchmark is an agent skill. Benchmark Xcode clean, incremental, and zero-change builds to establish performance baselines and measure build duration overhead.
Summary generated from the skill's SKILL.md.
About the xcode-build-benchmark skill
Establishing performance baselines for iOS development is what this skill enables by measuring Xcode build durations. Developers use it to capture clean, incremental, and zero-change build metrics to understand exactly how long builds take before attempting any optimizations. It is particularly useful when a user mentions build times or wants to see if recent changes made the build process faster or slower.
The tool executes a series of repeatable builds using the benchmark_builds.py script or direct xcodebuild commands with the -showBuildTimingSummary flag. It handles complex scenarios like warming up a compilation cache when COMPILATION_CACHE_ENABLE_CACHING is set to YES and manages specific requirements for git worktrees by creating missing directories for SPM packages.
Every run produces timestamped JSON artifacts stored in a .build-benchmark/ directory. Instead of just reporting a single fast run, the skill provides medians, minimums, and maximums for various build types. This includes measuring the fixed overhead floor through zero-change builds and real edit-rebuild loops via the --touch-file flag.
What an agent can do with it
- 1Establish a performance baselineCreate a repeatable Xcode build baseline before anyone tries to optimize build times.
- 2Measure build duration overheadDetermine the fixed overhead floor by running zero-change builds to check for avoidable per-build delays.
- 3Compare build performance changesCheck if recent project modifications have made the build process faster or slower.
- 4Simulate real edit-rebuild loopsMeasure how long an incremental build takes after a specific source file is modified.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the xcode-build-benchmark skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the xcode-build-benchmark skill in Plugin
/plugin marketplace add AvdLee/Xcode-Build-Optimization-Agent-Skill /plugin install xcode-build-skills@xcode-build-skills
Install the xcode-build-benchmark skill in Claude Code
~/.claude/skills/xcode-build-benchmark/SKILL.md
$ npx degit AvdLee/Xcode-Build-Optimization-Agent-Skill/skills/xcode-build-benchmark ~/.claude/skills/xcode-build-benchmarkInstall the xcode-build-benchmark skill in Claude Code (project)
.claude/skills/xcode-build-benchmark/SKILL.md
$ npx degit AvdLee/Xcode-Build-Optimization-Agent-Skill/skills/xcode-build-benchmark .claude/skills/xcode-build-benchmarkInstall the xcode-build-benchmark skill in Codex
~/.agents/skills/xcode-build-benchmark/SKILL.md
$ npx degit AvdLee/Xcode-Build-Optimization-Agent-Skill/skills/xcode-build-benchmark ~/.agents/skills/xcode-build-benchmarkInstall the xcode-build-benchmark skill in Gemini CLI
~/.gemini/skills/xcode-build-benchmark/SKILL.md
$ npx degit AvdLee/Xcode-Build-Optimization-Agent-Skill/skills/xcode-build-benchmark ~/.gemini/skills/xcode-build-benchmarkInstall the xcode-build-benchmark skill in Claude.ai
npx degit AvdLee/Xcode-Build-Optimization-Agent-Skill/skills/xcode-build-benchmark xcode-build-benchmark && zip -r xcode-build-benchmark.zip xcode-build-benchmark # claude.ai → Customize → Skills → + → Create skill → Upload a skill → xcode-build-benchmark.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachableavdlee/xcode-build-optimization-agent-skill/skills/xcode-build-benchmark is public and reachablegithub.com/avdlee/xcode-build-optimization-agent-skill/tree/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-09-14github.com/avdlee/xcode-build-optimization-agent-skill/commi ↗Pass
- No download-and-run or credential theft in scripts1 script read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/avdlee/xcode-build-optimization-agent-skill/blob/ ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/avdlee/xcode-build-optimization-agent-skill/blob/ ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 89 linesgithub.com/avdlee/xcode-build-optimization-agent-skill/blob/ ↗Pass
SKILL.md
View on GitHubXcode Build Benchmark
Use this skill to produce a repeatable Xcode build baseline before anyone tries to optimize build times.
Core Rules
- Measure before recommending changes.
- Capture clean and incremental builds separately.
- Keep the command, destination, configuration, scheme, and warm-up rules consistent across runs.
- Write a timestamped JSON artifact to
.build-benchmark/. - Do not change project files as part of benchmarking.
Inputs To Collect
Confirm or infer:
- workspace or project path
- scheme
- configuration
- destination
- whether the user wants simulator or device numbers
- whether a custom
DerivedDatapath is needed
If the project has both clean-build and incremental-build pain, benchmark both. That is the default.
Worktree Considerations
When benchmarking inside a git worktree, SPM packages with exclude: paths that reference gitignored directories (e.g., __Snapshots__) will cause xcodebuild -resolvePackageDependencies to crash. Create those missing directories before running any builds.
Default Workflow
- Normalize the build command and note every flag that affects caching or module reuse.
- Run one warm-up build if needed to validate that the command succeeds.
- Run 3 clean builds.
- If
COMPILATION_CACHE_ENABLE_CACHING = YESis detected, run 3 cached clean builds. These measure clean build time with a warm compilation cache -- the realistic scenario for branch switching, pulling changes, or Clean Build Folder. The script handles this automatically by building once to warm the cache, then deleting DerivedData (but not the compilation cache) before each measured run. Pass--no-cached-cleanto skip. - Run 3 zero-change builds (build immediately after a successful build with no edits). This measures the fixed overhead floor: dependency computation, project description transfer, build description creation, script phases, codesigning, and validation. A zero-change build that takes more than a few seconds indicates avoidable per-build overhead. Use the default
benchmark_builds.pyinvocation (no--touch-fileflag). - Optionally run 3 incremental builds with a file touch to measure a real edit-rebuild loop. Use
--touch-file path/to/SomeFile.swiftto touch a representative source file before each build. - Save the raw results and summary into
.build-benchmark/. - Report medians and spread, not just the single fastest run.
Preferred Command Path
Use the shared helper when possible:
python3 scripts/benchmark_builds.py \
--workspace App.xcworkspace \
--scheme MyApp \
--configuration Debug \
--destination "platform=iOS Simulator,name=iPhone 16" \
--output-dir .build-benchmark
If you cannot use the helper script, run equivalent xcodebuild commands with -showBuildTimingSummary and preserve the raw output.
Required Output
Return:
- clean build median, min, max
- cached clean build median, min, max (when COMPILATION_CACHE_ENABLE_CACHING is enabled)
- zero-change build median, min, max (fixed overhead floor)
- incremental build median, min, max (if
--touch-filewas used) - biggest timing-summary categories
- environment details that could affect comparisons
- path to the saved artifact
If results are noisy, say so and recommend rerunning under calmer conditions.
When To Stop
Stop after measurement if the user only asked for benchmarking. If they want optimization guidance, hand off the artifact to the relevant specialist by reading its SKILL.md and applying its workflow to the same project context:
xcode-compilation-analyzerxcode-project-analyzerspm-build-analysisxcode-build-orchestratorfor full orchestration
Additional Resources
- For the benchmark contract, see references/benchmarking-workflow.md
- For the shared artifact format, see references/benchmark-artifacts.md
- For the JSON schema, see schemas/build-benchmark.schema.json
Files in this skill
5xcode-build-benchmark skill questions
How do I install the xcode-build-benchmark skill in Claude Code?
Run npx degit AvdLee/Xcode-Build-Optimization-Agent-Skill/skills/xcode-build-benchmark ~/.claude/skills/xcode-build-benchmark. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the xcode-build-benchmark skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How are the benchmark results stored?
Results are saved as timestamped JSON artifacts in a directory named .build-benchmark/.
What should I do if I encounter crashes when using git worktrees?
If using a git worktree with SPM packages that reference gitignored directories, you must create those missing directories before running builds to prevent xcodebuild from crashing.