avdlee/core-data-agent-skill
Overview
This skill provides expert, production-focused guidance for Apple Core Data on iOS and macOS. It helps set up correct stacks, design fetch requests, handle threading and Swift Concurrency, resolve merge/saving conflicts, run batch operations and migrations, and integrate with NSPersistentCloudKitContainer for CloudKit sync. Advice is practical and immediately actionable for bug fixes and performance tuning.
How this skill works
I triage problems by first clarifying platform and deployment target, store type, context usage, and error details. Recommendations branch by context (UI view context vs background work), and always prefer NSManagedObjectID for cross-context communication. I point to targeted procedures for stack setup, saving patterns, threading, concurrency, batch ops, persistent history, migrations, and CloudKit rules.
When to use it
- Setting up a new Core Data stack or choosing store/merge policies
- Fixing crashes related to cross-context access or threading
- Optimizing slow fetches, memory use, or batch operations
- Implementing or debugging migrations and versioning errors
- Integrating NSPersistentCloudKitContainer and resolving sync issues
Best practices
- Always identify UI (view) vs background context before changing code
- Never pass NSManagedObject between contexts—use NSManagedObjectID
- Enable persistent history tracking when using batch operations that must update UI
- Prefer lightweight migration; use staged/deferred migration for complex schema changes
- Profile with Instruments before changing fetch or caching strategies
- Treat CloudKit production schema as immutable and plan schema changes carefully
Example use cases
- Resolve a crash where a background thread updates a UI-managed NSManagedObject by switching to NSManagedObjectID handoff
- Improve list scrolling by adding fetch batchSize, and using NSFetchRequest limits and faults
- Apply a migration path after encountering NSPersistentStoreIncompatibleVersionHashError
- Make batch deletes visible to the UI by enabling persistent history tracking and merging changes
- Debug CloudKit sync stalls by verifying container configuration and production schema constraints
FAQ
Never pass NSManagedObject instances—use NSManagedObjectID and re-fetch in the receiving context.
When should I enable persistent history tracking?
Enable it whenever using batch insert/update/delete or multiple processes so changes can be merged into view contexts.
Lightweight migration failed—what next?
Confirm model versions and consider staged or custom migration; collect logs and migration errors to choose a strategy.
