/cloudkit-sync

name: cloudkit-sync
description: Generate CloudKit sync infrastructure using CKSyncEngine with conflict resolution, sharing, and account monitoring. Use when adding iCloud sync to an iOS/macOS app.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
last_verified: 2026-07-16
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

CloudKit Sync Generator

Generate production-ready CloudKit sync infrastructure using `CKSyncEngine` (iOS 17+ / macOS 14+), the modern replacement for manual `CKOperation` chains.

When This Skill Activates

Use this skill when the user:

• Asks to "add iCloud sync" or "sync data across devices"
• Mentions "CloudKit", "CKSyncEngine", or "cloud sync"
• Wants to "share data between users" via iCloud
• Asks about "conflict resolution" for synced data
• Mentions "CKRecord", "CKShare", or "CKRecordZone"

Pre-Generation Checks

1. Project Context Detection

Before generating, ALWAYS check:

# Check deployment target (CKSyncEngine requires iOS 17+ / macOS 14+)
grep -r "platform" Package.swift 2>/dev/null || true
grep -r "IPHONEOS_DEPLOYMENT_TARGET\|MACOSX_DEPLOYMENT_TARGET" --include="*.pbxproj" | head -3

# Find existing CloudKit implementations
rg -l "CKSyncEngine\|CKContainer\|CKRecord\|CKOperation" --type swift | head -10

# Check for existing entitlements
find . -name "*.entitlements" -exec cat {} \; 2>/dev/null | grep -i "icloud"

# Check existing persistence layer
rg -l "@Model\|NSManagedObject\|PersistentModel" --type swift | head -5

# Check for existing sync infrastructure
rg "CKSyncEngineDelegate\|CKSubscription\|CKFetchRecordZoneChanges" --type swift | head -5

2. Compatibility Verification

**CKSyncEngine requires:**

• iOS 17.0+ / macOS 14.0+ / watchOS 10.0+ / tvOS 17.0+
• CloudKit entitlement
• Active iCloud account on device

If deployment target is below iOS 17 / macOS 14, warn the user that CKSyncEngine is not available and suggest either raising the target or using the older CKOperation approach (which this generator does not cover).

3. Conflict Detection

If existing CloudKit code is found:

• Ask: Replace existing implementation, extend it, or migrate to CKSyncEngine?

Configuration Questions

Ask user via AskUserQuestion:

1. **What data needs syncing?**

• Provide your model types (e.g., Note, Task, Document)
• What properties does each model have?

2. **Database scope?**

• Private only (user's own data across their devices)
• Private + Shared (enable CKShare for collaboration)

3. **Conflict resolution strategy?**

• Server-wins (simplest -- always accept server version)
• Client-wins (always push local version)
• Timestamp-based merge (most recent modification wins)
• Custom merge (field-level merge logic)

4. **Existing persistence layer?**

• SwiftData (will generate CKRecord <-> SwiftData bridging)
• Core Data (will generate CKRecord <-> NSManagedObject bridging)
• Custom / in-memory (will generate standalone CKRecord mapping)
• None yet (will generate lightweight local store + sync)

Generation Process

Step 1: Read Templates

Read code templates from this skill:

• `templates.md` - All CKSyncEngine code templates

Step 2: Create Core Files

Generate these files based on configuration:

**Always generate:**

Sources/CloudSync/
├── SyncEngine.swift              # CKSyncEngine setup + CKSyncEngineDelegate
├── SyncConfiguration.swift       # Zone names, container ID, database scope
├── RecordMapping.swift           # CKRecord <-> local model conversion
├── ConflictResolver.swift        # Conflict resolution strategy
├── SyncMonitor.swift             # Account status + sync state observation
└── CloudSyncError.swift          # Typed error handling with CKError mapping

**If sharing enabled:**

Sources/CloudSync/Sharing/
├── ShareManager.swift            # CKShare creation and management
└── ShareParticipantView.swift    # UICloudSharingController wrapper

Step 3: Determine File Location

Check project structure:

• If `Sources/` exists -> `Sources/CloudSync/`
• If `App/` exists -> `App/CloudSync/`
• Otherwise -> `CloudSync/`

Step 4: Customize for Project

Adapt templates to match:

• User's model types and property names
• Bundle identifier for CloudKit container ID
• Chosen conflict resolution strategy
• Database scope (private only vs. private + shared)

Step 5: Entitlements Setup

Generate or update entitlements file with required CloudKit capabilities.

Entitlements and Capabilities Setup

Required Xcode Capabilities

1. **iCloud** capability:

• Check "CloudKit"
• Add container: `iCloud.com.<team-identifier>.<app-bundle-id>`

2. **Background Modes** (recommended):

• Check "Remote notifications" (for push-based sync triggers)

Required 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.icloud-container-identifiers</key>
    <array>
        <string>iCloud.com.yourcompany.yourapp</string>
    </array>
    <key>com.apple.developer.icloud-services</key>
    <array>
        <string>CloudKit</string>
    </array>
</dict>
</plist>

CloudKit Dashboard Setup

1. Go to [CloudKit Dashboard](https://icloud.developer.apple.com/) 2. Select your container 3. Record types are auto-created when you first save a CKRecord of that type during development 4. **Deploy schema to production before App Store release** 5. Indexes are required for queryable fields -- add them in the dashboard

Output Format

After generation, provide:

Files Created

Sources/CloudSync/
├── SyncEngine.swift              # CKSyncEngine + delegate implementation
├── SyncConfiguration.swift       # Container, zone, and scope config
├── RecordMapping.swift           # CKRecord <-> model bridging
├── ConflictResolver.swift        # Pluggable conflict resolution
├─