Xcode Build Optimization Agent Skills

Open-source Agent Skills for benchmarking and optimizing Xcode build performance across clean builds, incremental builds, compile hotspots, project settings, and Swift Package Manager overhead.

Quick Start

Install the orchestrator skill:

npx skills add https://github.com/avdlee/xcode-build-optimization-agent-skill --skill xcode-build-orchestrator

Then open your Xcode project in your AI coding tool and say:

Use the Xcode build orchestrator to analyze build performance and come up with a plan for improvements.

The agent will benchmark your clean and incremental builds, audit build settings, find compile hotspots, and produce an optimization plan at .build-benchmark/optimization-plan.md. No project files are modified until you explicitly approve changes.

For long-term monitoring across days, machines, Xcode versions, and teams, use RocketSim Build Insights and Team Build Insights.

See Also My Other Skills

• Swift Concurrency Expert
• SwiftUI Expert
• Core Data Expert
• Swift Testing Expert

Who This Is For

• iOS and macOS teams with slow local build loops
• developers investigating a recent build-time regression
• teams that want evidence-backed Xcode build optimization instead of guesswork
• developers who want a reusable Agent Skills package, not a one-off script

Included Skills

Skill	Purpose
xcode-build-orchestrator	End-to-end workflow: benchmark, analyze, prioritize, approve, fix, re-benchmark
xcode-build-benchmark	Repeatable clean and incremental build benchmarks with timestamped artifacts
xcode-compilation-analyzer	Swift compile hotspot analysis and source-level recommendations
xcode-project-analyzer	Build settings, scheme, script phase, and target dependency auditing
spm-build-analysis	Package graph, plugin overhead, and module variant review
xcode-build-fixer	Apply approved optimization changes and verify with benchmarks

The orchestrator is the recommended starting point -- it coordinates the other five skills automatically.

Installation Options

Option A: Using skills.sh

Install a single skill:

npx skills add https://github.com/avdlee/xcode-build-optimization-agent-skill --skill xcode-build-orchestrator

Or install any of the six skills individually: xcode-build-benchmark, xcode-compilation-analyzer, xcode-project-analyzer, spm-build-analysis, xcode-build-orchestrator, xcode-build-fixer.

Option B: Claude Code Plugin

1. Add the marketplace:

/plugin marketplace add AvdLee/Xcode-Build-Optimization-Agent-Skill

2. Install the plugin:

/plugin install xcode-build-skills@xcode-build-skills

To enable for everyone in a repository, add to your project configuration:

{
  "enabledPlugins": {
    "xcode-build-skills@xcode-build-skills": true
  },
  "extraKnownMarketplaces": {
    "xcode-build-skills": {
      "source": {
        "source": "github",
        "repo": "AvdLee/Xcode-Build-Optimization-Agent-Skill"
      }
    }
  }
}

Option C: Manual Install

1. Clone this repository.
2. Install or symlink the specific skill folder from skills/ that you want.
3. Ask your AI coding tool to use the corresponding skill.

Useful docs: Codex Skills | Claude Code Agent Skills | Cursor Skills

How It Works

The orchestrator uses a two-phase recommend-first workflow that separates analysis from implementation.

Phase 1 -- Analyze. The agent benchmarks your project, runs all specialist analyses, and produces a markdown optimization plan at .build-benchmark/optimization-plan.md. The plan includes baseline benchmarks, a build settings audit, compilation diagnostics, and prioritized recommendations with an approval checklist. No project files are modified.

Use the Xcode build orchestrator to analyze build performance and come up with a plan for improvements.

Phase 2 -- Fix. After reviewing the plan, check the approval boxes for the recommendations you want and ask the agent to implement them. It applies only the approved changes, re-benchmarks, and reports the measured improvement.

Implement the approved items from the optimization plan at .build-benchmark/optimization-plan.md, then re-benchmark to verify the improvements.

The plan file becomes the evidence trail -- shareable with teammates, reviewable in pull requests, and diffable over time.

Why Clean And Incremental Builds Both Matter

Clean builds expose:

• package and module setup cost
• full project graph overhead
• target structure and explicit-module issues

Incremental builds expose:

• edit-loop pain
• run script bottlenecks
• cache invalidation problems
• repeated package-plugin overhead

That distinction is central to this repo and follows both Apple's Xcode guidance and the SwiftLee workflow in Build performance analysis for speeding up Xcode builds.

Shared Support Layer

The skills share:

• a common .build-benchmark/ artifact contract
• a shared JSON schema for benchmark output
• helper scripts for benchmarking, timing-summary parsing, compilation diagnostics, report generation, and recommendation rendering
• a build settings best practices reference for the pass/fail audit
• a single source summary file so README and skill guidance stay aligned

Skill Structure

xcode-build-optimization-agent-skill/
  .claude-plugin/
    marketplace.json
    plugin.json
  references/
    benchmark-artifacts.md
    build-optimization-sources.md
    build-settings-best-practices.md
    recommendation-format.md
  schemas/
    build-benchmark.schema.json
  scripts/
    benchmark_builds.py
    check_spm_pins.py
    diagnose_compilation.py
    generate_optimization_report.py
    render_recommendations.py
    summarize_build_timing.py
  skills/
    xcode-build-benchmark/
      SKILL.md
      references/
        benchmarking-workflow.md - Benchmark contract, clean vs incremental rules, and artifact expectations
    xcode-compilation-analyzer/
      SKILL.md
      references/
        code-compilation-checks.md - Swift compile hotspot checks and code-level heuristics
    xcode-project-analyzer/
      SKILL.md
      references/
        project-audit-checks.md - Build setting, script phase, and dependency audit checklist
    spm-build-analysis/
      SKILL.md
      references/
        spm-analysis-checks.md - Package graph, plugin overhead, and module variant review guide
    xcode-build-orchestrator/
      SKILL.md
      references/
        orchestration-report-template.md - Prioritization, approval, and verification report template
    xcode-build-fixer/
      SKILL.md
      references/
        fix-patterns.md - Concrete before/after patterns for each fix category

Research Basis

This repo deliberately aligns with:

• Apple's incremental-build guidance: accurate target dependencies, script input/output declarations, module maps, and parallel-friendly project structure
• Apple's compile-efficiency guidance: explicit type information, simpler expressions, narrower bridging surfaces, and framework-qualified imports
• Apple's explicit module dependency guidance: reducing duplicate module variants caused by configuration drift
• the SwiftLee workflow for measuring with Build Timeline, Build Timing Summary, and Swift frontend diagnostics

The stored reference summaries live in references/build-optimization-sources.md.

RocketSim Positioning

This repo helps you optimize point-in-time build performance with an agent-guided workflow.

RocketSim complements it by monitoring build performance over time:

• automatic clean vs incremental build tracking
• duration trends and percentile metrics
• machine, Xcode, and macOS comparisons
• team-wide visibility without custom build scripts

If you want to catch regressions earlier and see whether your build times are improving over weeks or months, use RocketSim Build Insights after you apply the improvements from this repo.

Community Results

Real-world improvements reported by developers who used these skills. Add your own results by opening a pull request.

The xcode-build-orchestrator generates your table row at the end of every optimization run, so contributing is a single copy-paste.

App	Incremental Before	Incremental After	Clean Before	Clean After	Cached Clean Before	Cached Clean After

Contributing

Contributions are welcome when they keep the repo focused on Xcode build optimization and Agent Skills format quality.

Please read CONTRIBUTING.md for:

• skill-authoring guidance
• repo scope and quality standards
• workflow notes for scripts and README sync

About The Author

Created by Antoine van der Lee, creator of SwiftLee and RocketSim. The practical build workflow in this repository is informed by the SwiftLee article Build performance analysis for speeding up Xcode builds and ongoing work on RocketSim Build Insights.

License

This repository is available under the MIT License. See LICENSE for details.