using-xtool

Use when building iOS apps with xtool (Xcode-free iOS development), creating xtool projects, adding app extensions (widgets, share extensions), or configuring xtool.yml. Triggers on mentions of xtool, SwiftPM iOS apps, building iOS on Linux/Windows, or app extension setup.

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 2, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill facilitates Xcode-free iOS development using xtool, a cross-platform tool for building SwiftPM-based iOS applications on Linux, Windows, and macOS. It provides comprehensive support for project initialization, xtool.yml configuration, app extension integration (like Widgets and Share extensions), and seamless deployment to iOS devices and simulators without the need for traditional .xcodeproj files.

Use Cases

  • Cross-platform iOS Development: Building, compiling, and testing iOS applications on Linux or Windows environments using the SwiftPM workflow.
  • Project Configuration & Setup: Initializing new iOS projects and configuring xtool.yml for bundle IDs, entitlements, and resource management.
  • App Extension Integration: Adding and configuring specialized targets such as WidgetKit, Share, and Safari extensions using a library-based SwiftPM approach.
  • Device & Identity Management: Handling Apple developer authentication, managing provisioning profiles, and deploying IPAs directly to physical iOS devices via CLI.
  • CI/CD Automation: Integrating iOS build and deployment processes into automated pipelines that run on non-macOS build agents.
nameusing-xtool
descriptionThis skill should be used when building iOS apps with xtool (Xcode-free iOS development), creating xtool projects, adding app extensions, or configuring xtool.yml. Triggers on "xtool", "SwiftPM iOS", "iOS on Linux", "iOS on Windows", "Xcode-free", "app extension", "widget extension", "share extension". Covers project setup, app extensions, and deployment.

Using xtool

Overview

xtool is a cross-platform Xcode replacement for building iOS apps with SwiftPM on Linux, Windows, and macOS. It is NOT XcodeGen, Tuist, or Xcode project files.

Critical: xtool is NOT XcodeGen

xtool Uses NOT These
xtool.yml project.yml, Project.swift
Package.swift (SwiftPM) Xcode project files
xtool dev xtool build, xtool run, xtool generate
Sources/ directory Extensions/ directory

Project Structure

MyApp/
├── Package.swift          # SwiftPM package definition
├── xtool.yml              # xtool configuration
├── Sources/
│   ├── MyApp/             # Main app target
│   │   ├── MyAppApp.swift
│   │   └── ContentView.swift
│   └── MyWidget/          # Extension target (if any)
│       └── Widget.swift
├── MyApp-Info.plist       # Optional custom Info.plist
└── MyWidget-Info.plist    # Required for extensions

Quick Reference: Commands

# Project lifecycle
xtool new MyApp              # Create new project
xtool new MyApp --skip-setup # Create without running setup
xtool dev                    # Build + run (same as `xtool dev run`)
xtool dev build              # Build only
xtool dev build --ipa        # Build IPA file
xtool dev run -s             # Run on iOS Simulator (--simulator)
xtool dev run -c release     # Release build (--configuration)
xtool dev run -u <udid>      # Target specific device (--udid)
xtool dev generate-xcode-project  # Generate .xcodeproj for debugging

# Device management
xtool devices                # List connected devices
xtool install app.ipa        # Install IPA to device
xtool launch                 # Launch installed app
xtool uninstall              # Uninstall app from device

# Authentication & setup
xtool setup                  # Full setup (auth + SDK)
xtool auth login             # Authenticate with Apple
xtool auth status            # Check auth status
xtool auth logout            # Log out
xtool sdk                    # Manage Darwin Swift SDK

# Developer Services
xtool ds teams               # List development teams
xtool ds certificates        # Manage certificates
xtool ds profiles            # Manage provisioning profiles

xtool.yml Format

Minimal:

version: 1
bundleID: com.example.MyApp

Full options:

version: 1
bundleID: com.example.MyApp
product: MyApp                    # Which SwiftPM product is main app
infoPath: MyApp-Info.plist        # Custom Info.plist (merged)
iconPath: Resources/AppIcon.png   # App icon (1024x1024 PNG)
entitlementsPath: App.entitlements
resources:                        # Files copied to app bundle root
  - Resources/GoogleServices-Info.plist
extensions:                       # App extensions
  - product: MyWidget
    infoPath: MyWidget-Info.plist

Adding App Extensions (Widgets, Share, etc.)

Step 1: Update Package.swift

Add BOTH a product AND a target. Note: xtool uses .library (not .executable) - it bundles the library into an iOS app.

// swift-tools-version: 6.0
import PackageDescription

let package = Package(
    name: "MyApp",
    platforms: [.iOS(.v17)],
    products: [
        .library(name: "MyApp", targets: ["MyApp"]),
        .library(name: "MyWidget", targets: ["MyWidget"]),  // ADD
    ],
    targets: [
        .target(name: "MyApp"),
        .target(name: "MyWidget"),  // ADD
    ]
)

Step 2: Update xtool.yml

version: 1
bundleID: com.example.MyApp
product: MyApp
extensions:
  - product: MyWidget
    infoPath: MyWidget-Info.plist

Step 3: Create Extension Info.plist

Minimal required (just the extension type):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSExtension</key>
    <dict>
        <key>NSExtensionPointIdentifier</key>
        <string>com.apple.widgetkit-extension</string>
    </dict>
</dict>
</plist>

Step 4: Create Extension Code

Sources/MyWidget/Widget.swift:

import WidgetKit
import SwiftUI

@main struct MyWidgetBundle: WidgetBundle {
    var body: some Widget { MyWidget() }
}

struct MyWidget: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(kind: "MyWidget", provider: Provider()) { entry in
            Text(entry.date, style: .date)
                .containerBackground(.fill.tertiary, for: .widget)
        }
        .configurationDisplayName("My Widget")
    }
}

struct Entry: TimelineEntry { var date = Date() }

struct Provider: TimelineProvider {
    func placeholder(in context: Context) -> Entry { Entry() }
    func getSnapshot(in context: Context, completion: @escaping (Entry) -> Void) {
        completion(Entry())
    }
    func getTimeline(in context: Context, completion: @escaping (Entry) -> Void) {
        completion(Timeline(entries: [Entry()], policy: .after(.now + 3600)))
    }
}

Step 5: Build and Run

xtool dev

Common Extension Types

Extension NSExtensionPointIdentifier
Widget (WidgetKit) com.apple.widgetkit-extension
Share com.apple.share-services
Action com.apple.ui-services
Safari com.apple.Safari.web-extension
Keyboard com.apple.keyboard-service
Today (deprecated) com.apple.widget-extension

Troubleshooting

Error Solution
"Untrusted Developer" Settings > General > VPN & Device Management > Trust
Device not found Connect USB, run xtool devices, enable Developer Mode
Auth failed Run xtool auth login
Build fails on first run Normal - SDK modules building. Wait for completion.

Resources Configuration

SwiftPM resources (in bundle subdirectory):

.target(name: "MyApp", resources: [.copy("Blob.png")])
// Access: Image("Blob", bundle: Bundle.module)

Top-level resources (in app bundle root):

# xtool.yml
resources:
  - Resources/GoogleServices-Info.plist

Entitlements

# xtool.yml
entitlementsPath: App.entitlements
<!-- App.entitlements -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.homekit</key>
    <true/>
</dict>
</plist>

Common Mistakes

Mistake Fix
Using xtool build Use xtool dev build
Using project.yml Use xtool.yml
Using Extensions/ dir Use Sources/ (standard SwiftPM)
Forgetting Package.swift Extensions need product + target in Package.swift
Complex extension Info.plist Only NSExtension/NSExtensionPointIdentifier required