CloudKit

Storing and syncing data to iCloud on Apple platforms: containers, the three database scopes, records, queries, subscriptions, sharing, and sync. The deep API reference — setup, every class, CRUD, querying, subscriptions, CKSyncEngine, conflict resolution, error handling, SwiftUI integration — lives in references/guide.md. This file is the decision and discipline layer: read it first, open the guide for specifics.

Dials

Set these explicitly at the start; they change what "correct" means.

1. DATABASE_SCOPE — private (default; per-user data, counts against the user's iCloud quota, requires sign-in) · public (shared by all users, counts against the app's quota, readable signed-out) · shared (collaboration via CKShare). Most apps are private-only; reach for public/shared only for leaderboards/feeds or real collaboration.
2. SYNC_STRATEGY — manual (you drive CKDatabase/CKModifyRecordsOperation/CKFetchRecordZoneChangesOperation + subscriptions; full control, more code) · sync-engine (iOS 17+ CKSyncEngine, owns scheduling/retries/batching — you keep local persistence and a delegate) · swiftdata (let SwiftData/Core Data mirror a local store to CloudKit — least code, no public/shared, no custom record types). Pick swiftdata unless you need public/shared databases or direct record control.
3. OFFLINE — online-only (act directly on the server; simplest, fails without network) · offline-first (local store is source of truth, CloudKit is the sync layer; required for a real sync app and the natural fit for sync-engine).

When to use

Building or reviewing any code that talks to CloudKit directly — containers, records, queries, subscriptions, sharing, or sync. For a local model that just needs iCloud mirroring, prefer the swiftdata skill (SwiftData syncs via CloudKit with almost no CloudKit code); use this skill when you need public/shared databases, CKShare, custom zones, or raw CKRecord access.

Core rules