macos-developer-toolchain
/macos-developer-toolchain
macOS developer toolchain management: Xcode versions and lifecycle, Swift migration (5.9 to 6.0 to 6.2), code signing, notarization, Command Line Tools, Foundation Models, CI/CD pipelines, and Homebrew. Covers Xcode 15 through Xcode 26 and macOS 14 Sonoma through macOS 26 Tahoe. Use when: \"Xcode\", \"xcode\", \"Swift\", \"swift\", \"codesign\", \"notarize\", \"notarytool\", \"stapler\", \"Developer ID\", \"code signing\", \"provisioning profile\", \"xcode-select\", \"Command Line Tools\", \"CLT\", \"Foundation Models\". Do NOT use for general macOS system administration — use the `macos` skil
- Author
- chrishuffman5 ↗
- Repository
- domain-expert ↗
- Licence
- MIT
- Last repository change
- 23.09.2026
Assessment and security
- Files in this package
- 7
- Scripts
- 3
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 23.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 3 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/01-xcode-health.sh, scripts/02-signing-audit.sh, scripts/03-homebrew-health.sh
What it does and when to use it
macOS developer toolchain management: Xcode versions and lifecycle, Swift migration (5.9 to 6.0 to 6.2), code signing, notarization, Command Line Tools, Foundation Models, CI/CD pipelines, and Homebrew. Covers Xcode 15 through Xcode 26 and macOS 14 Sonoma through macOS 26 Tahoe. Use when: \"Xcode\", \"xcode\", \"Swift\", \"swift\", \"codesign\", \"notarize\", \"notarytool\", \"stapler\", \"Developer ID\", \"code signing\", \"provisioning profile\", \"xcode-select\", \"Command Line Tools\", \"CLT\", \"Foundation Models\". Do NOT use for general macOS system administration — use the `macos` skil
Triggers from the description
Original author description
macOS developer toolchain management: Xcode versions and lifecycle, Swift migration (5.9 to 6.0 to 6.2), code signing, notarization, Command Line Tools, Foundation Models, CI/CD pipelines, and Homebrew. Covers Xcode 15 through Xcode 26 and macOS 14 Sonoma through macOS 26 Tahoe. Use when: \"Xcode\", \"xcode\", \"Swift\", \"swift\", \"codesign\", \"notarize\", \"notarytool\", \"stapler\", \"Developer ID\", \"code signing\", \"provisioning profile\", \"xcode-select\", \"Command Line Tools\", \"CLT\", \"Foundation Models\". Do NOT use for general macOS system administration — use the `macos` skil
How it works
- How to Approach Tasks
- Core Expertise
- Troubleshooting Decision Tree
- Common Pitfalls
- Reference Files
- Diagnostic Scripts
- Key Paths and Files
- Key Commands Quick Reference
SKILL.md preview
--- name: macos-developer-toolchain description: "macOS developer toolchain management: Xcode versions and lifecycle, Swift migration (5.9 to 6.0 to 6.2), code signing, notarization, Command Line Tools, Foundation Models, CI/CD pipelines, and Homebrew. Covers Xcode 15 through Xcode 26 and macOS 14 Sonoma through macOS 26 Tahoe. Use when: \"Xcode\", \"xcode\", \"Swift\", \"swift\", \"codesign\", \"notarize\", \"notarytool\", \"stapler\", \"Developer ID\", \"code signing\", \"provisioning profile\", \"xcode-select\", \"Command Line Tools\", \"CLT\", \"Foundation Models\". Do NOT use for general macOS system administration — use the `macos` skill." license: MIT --- # Developer Toolchain (macOS) This skill covers macOS developer toolchain management across Xcode 15, 16, and 26, covering macOS 14 Sonoma through macOS 26 Tahoe. It provides deep knowledge of: - Xcode versions and SDK mapping: Xcode 15 (Swift 5.9, macOS 14 SDK), Xcode 16 (Swift 6.0, macOS 15 SDK), Xcode 26 (Swift 6.2, macOS 26 SDK) - Xcode installation and multi-version coexistence: xcode-select, xcrun tool resolution, Spotlight discovery - Xcode Command Line Tools (CLT): standalone installation, headless/MDM deployment, CLT vs full Xcode - Swift version management: Swift 5.9 macros, Swift 6.0 strict concurrency, Swift 6.2 Foundation Models and embedded Swift - Code signing: certificate types, Keychain identity management, codesign flags, Hardened Runtime, entitlements - Notarization: notarytool workflow, App Store Connect API keys, stapler, async submission, rejection debugging - Provisioning profiles: types, inspection, CI/CD management, automatic vs manual signing - Gatekeeper and SIP: assessment, troubleshooting blocked applications - CI/CD pipelines: GitHub Actions macOS runners, xcodebuild, xcresult analysis, Fastlane integration - Foundation Models (macOS 26): on-device AI, LanguageModelSession, @Generable, Tool calling - Homebrew: Apple Silicon vs Intel paths, brew doctor, taps, casks, disk usage - Certificate lifecycle: creation, expiry monitoring, MDM deployment, automatic vs manual signing - Build optimization: Xcode 26 compilation caching, Swift Package Manager, dependency resolution When a question is version-specific, note the relevant differences. When the Xcode or macOS version is unknown, provide general guidance and flag where behavior varies. For general macOS administration, see the `macos` skill. ## How to Approach Tasks Route by request type: **Xcode/SDK** → `references/xcode-versions.md`; **Swift migration** → `references/swift-migration.md`; **signing/notarization** → `references/signing-notarization.md`; **health check** → the diagnostic scripts; **CI/CD signing** → `references/signing-notarization.md`. **Identify Xcode version, macOS version, and target platform first** — these determine available SDKs, Swift features, and signing requirements. Reason from the interaction between Xcode version, Swift version, signing identity, and deployment target to isolate whether the issue is installation, configuration, signing, or build-related. Use `xcrun` for tool resolution rather than hard-coded paths; prefer non-destructive diagnostic steps first. Validate with `xcodebuild -version`, `codesign --verify`, `stapler validate`, and `security find-identity`. ## Core Expertise ### Xcode Versions and SDK Mapping Apple ships one major Xcode version per macOS release. Each bundles a specific SDK and Swift toolchain. | Xcode | macOS Codename | Min Host macOS | Bundled Swift | Key SDK | |---|---|---|---|---| | 15.x | Sonoma era | macOS 13 Ventura | Swift 5.9 | macOS 14 SDK | | 16.x | Sequoia era | macOS 14 Sonoma | Swift 6.0 | macOS 15 SDK | | 26.x | Tahoe era | macOS 15 Sequoia | Swift 6.2 | macOS 26 SDK | Note: Xcode jumped from 16 to 26 to align with the macOS 26 "Tahoe" branding cycle. Multiple Xcode installations coexist by renaming (e.g., `Xcode-16.app`, `Xcode-26.app`). Each is self-contained. Switching requires only `xcode-select --switch`. **Active developer directory** controls which tools `xcrun` resolves: ```bash xcode-select --print-path # show current sudo xcode-select --switch /Applications/Xcode-26.app/Contents/Developer # switch ``` ### Command Line Tools (CLT) CLT provides compilers and Unix tools without the full Xcode GUI -- appropriate for CI servers and headless machines. | Feature | CLT Only | Full Xcode | |---|---|---| | clang/clang++ | Yes | Yes | | swift compiler | Yes | Yes | | iOS/macOS SDKs | macOS SDK only | All platforms | | Simulator | No | Yes | | Interface Builder | No | Yes | | Disk footprint | ~2 GB | 12-30 GB | Install methods: ```bash # Interactive (GUI dialog) xcode-select --install # Headless/MDM softwareupdate --list | grep "Command Line" softwareupdate --install "Command Line Tools for Xcode-16" --agree-to-license # Silent from .pkg installer -pkg /tmp/Command_Line_Tools_for_Xcode_16.pkg -target / ``` ### Swift Version Management **Swift 5.9 (Xcode 15):** - Swift Macros (`@attached`, `@freestanding` compile-time code generation) - SwiftData (declarative CoreData successor) - Observation framework (`@Observable` macro) - Variadic generics (parameter packs) **Swift 6.0 (Xcode 16):** - Strict concurrency: data race safety enforced at compile time - Complete actor isolation by default - `Sendable` enforcement across module boundaries - Typed throws: `throws(ErrorType)` declarations - Migration: `SWIFT_STRICT_CONCURRENCY=complete` build setting **Swift 6.2 (Xcode 26):** - Foundation Models API: on-device Apple Intelligence model integration - `@MainActor` inference improvements (opt-in) - `nonisolated(unsafe)` for gradual strict concurrency migration - Embedded Swift for microcontrollers ### Code Signing Code signing cryptographically asserts software identity and detects tampering. The kernel enforces signing via Gatekeeper and SIP. **Certificate types:** | Type | Issued By | Used For | |---|---|---| | Apple Development | Apple (via team) | Development builds, device testing | | Apple Distribution | Apple (via team) | TestFlight, App Store | | Developer ID Application | Apple | Mac apps outside App Store | | Developer ID Installer | Apple | .pkg installers outside App Store | Developer ID is the critical certificate for enterprise Mac software. Without it, Gatekeeper blocks execution. **Hardened Runtime** is required for notarization: - Prevents code injection and unsigned dynamic library loading - Restricts DYLD environment variables - Enable with `--options runtime` in codesign - Exceptions declared via entitlements ### Notarization Notarization is Apple's automated malware scanning service. After passing, Apple issues a ticket that Gatekeeper checks at launch. **notarytool workflow:** ```bash # Store credentials (one-time) xcrun notarytool store-credentials "AC_PASSWORD" \ --key AuthKey.p8 --key-id KEYID --issuer ISSUERID # Submit and wait xcrun notarytool submit MyApp.zip --keychain-profile "AC_PASSWORD" --wait # Staple the ticket xcrun stapler staple MyApp.app # Validate xcrun stapler validate MyApp.app ``` Apple checks: Hardened Runtime enabled, no malware signatures, no private entitlements, secure timestamp present, all binaries signed. ### Foundation Models (macOS 26) On-device AI framework, part of Apple Intelligence: - Runs entirely on-device using Apple Neural Engine (ANE) - ~3B parameter model, quantized for M-series chips - Requires macOS 26+, Apple Silicon, Apple Intelligence enabled - MDM can control availability via `allowAppleIntelligence` restriction ```swift import FoundationModels let session = LanguageModelSession() let response = try await session.respond(to: "Summarize this document") ``` Advanced: `@Generable` for structured output, `Tool` protocol for tool calling. ### Homebrew Homebrew is the de facto package manager for macOS developer tools. | Architecture | Prefix | Notes | |---|---|---| | Apple Silicon (arm64) | `/opt/homebrew` | Native ARM packages | | Intel (x86_64) | `/usr/local` | Legacy path | Intel Homebrew on Apple Silicon (Rosetta 2) is a common misconfiguration. Detect with `brew --prefix` and compare to expected path for `uname -m`. ### Certificate Lifecycle - Developer ID certificates expire in **5 years** - Apple Development/Distribution certificates expire in **1 year** - APNs push certificates (for MDM) expire annually - Set calendar reminders; automate expiry monitoring ```bash # Check all signing identity expiry security find-identity -v -p codesigning # Check specific certificate security find-certificate -c "Developer ID Application" -p | openssl x509 -noout -enddate ``` ### CI/CD Best Practices - Download specific Xcode .xip from developer.apple.com for version pinning - Use temporary keychains in CI to avoid polluting system keychain - `set-key-partition-list` required on macOS 10.12+ for codesign access without UI prompts - Lock CI images to specific Xcode version; avoid App Store auto-updates - Use `xcrun` for tool resolution rather than absolute paths ## Troubleshooting Decision Tree ``` 1. Build failure +-- Missing SDK --> xcodebuild -showsdks; xcode-select --switch +-- Swift version mismatch --> swift --version; check TOOLCHAINS env var +-- Dependency resolution --> swift package resolve --verbose +-- License not accepted --> sudo xcodebuild -license accept | 2. Signing failure +-- No valid identity --> security find-identity -v -p codesigning +-- Certificate expired --> Check expiry; request new cert +-- Provisioning profile mismatch --> security cms -D -i profile +-- CI keychain access denied --> set-key-partition-list | 3. Notarization rejection +-- Missing Hardened Runtime --> codesign --display --verbose=4 +-- Unsigned nested bundle --> codesign --verify --deep --strict +-- Private entitlement --> codesign --display --entitlements :- +-- Retrieve rejection log --> notarytool log <uuid> | 4. Gatekeeper blocking +-- Not notarized --> xcrun stapler validate +-- Quarantine flag --> xattr -d com.apple.quarantine (manual override) +-- spctl --assess --type execute --verbose MyApp.app ``` ## Common Pitfalls **1. Active developer directory pointing to CLT instead of Xcode** CLT lacks iOS SDKs, simulators, and full signing tools. Verify with `xcode-select --print-path` and switch if needed. **2. TOOLCHAINS environment variable overriding Xcode bundled toolchain** A stale `TOOLCHAINS` env var can cause unexpected Swift version. Unset it or verify it matches your intended toolchain. **3. Missing set-key-partition-list in CI** On macOS 10.12+, imported certificates require `security set-key-partition-list` to allow codesign access without UI prompts. Without it, CI builds fail with "errSecInternalComponent." **4. App Store Xcode auto-updating and breaking CI** App Store can update Xcode automatically, changing the SDK and Swift version mid-pipeline. Pin Xcode versions via direct .xip download for CI. **5. Homebrew on Intel path on Apple Silicon** Running `/usr/local/bin/brew` on an arm64 Mac indicates a Rosetta 2 installation. Native arm64 packages are faster and avoid translation overhead. Migrate to `/opt/homebrew`. ## Reference Files Load these when you need deep knowledge for a specific area: - `references/xcode-versions.md` -- Xcode 15 through 26, SDK mapping, features per version. Read for version compatibility questions. - `references/swift-migration.md` -- Swift 5.9 to 6.0 to 6.2, concurrency migration. Read for Swift upgrade guidance. - `references/signing-notarization.md` -- Code signing, notarization pipeline, entitlements. Read for signing and distribution questions. ## Diagnostic Scripts Run these for rapid toolchain assessment: | Script | Purpose | |---|---| | `scripts/01-xcode-health.sh` | Xcode version, CLT, SDKs, Swift, simulators | | `scripts/02-signing-audit.sh` | Developer ID certs, expiry, provisioning profiles, Gatekeeper | | `scripts/03-homebrew-health.sh` | Install path, outdated packages, doctor, taps, disk usage | ## Key Paths and Files | Path | Purpose | |---|---| | `/Applications/Xcode.app` | Default Xcode installation | | `/Library/Developer/CommandLineTools/` | CLT standalone installation | | `~/Library/MobileDevice/Provisioning Profiles/` | Installed provisioning profiles | | `~/Library/Keychains/login.keychain-db` | User signing identities | | `/Library/Keychains/System.keychain` | System certificates | | `~/.swiftpm/cache` | Swift Package Manager cache | | `/opt/homebrew` | Homebrew prefix (Apple Silicon) | | `/usr/local` | Homebrew prefix (Intel) | ## Key Commands Quick Reference ```bash # Xcode management xcode-select --print-path sudo xcode-select --switch /Applications/Xcode-26.app/Contents/Developer xcodebuild -version xcodebuild -showsdks # Swift swift --version xcrun swift --version swift package resolve # CLT pkgutil --pkg-info=com.apple.pkg.CLTools_Executables xcode-select --install # Code signing security find-identity -v -p codesigning codesign --verify --deep --strict --verbose=2 MyApp.app codesign --display --verbose=4 MyApp.app codesign --display --entitlements :- MyApp.app # Notarization xcrun notarytool submit MyApp.zip --keychain-profile "AC_PASSWORD" --wait xcrun stapler staple MyApp.app xcrun stapler validate MyApp.app # Gatekeeper spctl --assess --type execute --verbose MyApp.app spctl --status # Provisioning profiles security cms -D -i profile.provisionprofile # Homebrew brew doctor brew outdated brew --prefix ```
Files in this package (7)
- SKILL.md 13 KB
- references/signing-notarization.md 10 KB
- references/swift-migration.md 8 KB
- references/xcode-versions.md 7 KB
- scripts/01-xcode-health.sh 6 KB
- scripts/02-signing-audit.sh 6 KB
- scripts/03-homebrew-health.sh 7 KB
Versions
The database has no other skills named macos-developer-toolchain.
Database snapshot: 13.11.2026 · package version 1c9da33e4e51 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100xcode
Expert Xcode assistance covering Swift/SwiftUI development, iOS/macOS simulators, Xcode Cloud CI/CD, Instruments profiling, and Swift Package Manager (SPM). Use when configuring Xcode projects, debugging iOS apps with LLDB, profiling with Instruments, or managing Apple Developer signing. - 100xcode-management
Xcode 项目管理和 iOS/macOS 开发工作流程方面的专家。专注于管理 Xcode 项目文件、理解 .pbxproj 格式,以及自动化文件添加到 Xcode 项目的过程。使用此技能管理 Xcode 项目、添加新文件到项目、配置构建设置或处理项目文件问题时使用。 - 90macos-build-run-debug
Build, run, and debug macOS apps with shell-first Xcode and Swift workflows. Use when launching apps or diagnosing build, startup, or runtime failures. - 100guide-macos-spm-packaging
Scaffold, build, and package SwiftPM-based macOS apps without an Xcode project. Use when you need a from-scratch macOS app layout, SwiftPM targets/resources, a custom .app bundle assembly script, or signing/notarization/appcast steps outside Xcode. - 90mac-app
Build, bundle, sign and ship a macOS app with SwiftPM and the Command Line Tools only, no Xcode project. Use when creating a menu bar or desktop Mac app from the terminal, turning a Swift package into a .app, fixing macOS permission (TCC) prompts that never appear or keep… - 90apple-developer
Build, debug, and review native macOS, iPadOS, and iOS apps. Use for Swift, SwiftUI, UIKit, AppKit, Xcode, performance, platform UX, accessibility, persistence, Apple APIs, privacy, signing, StoreKit, TestFlight, and App Store submission work.