home / skills / avdlee / core-data-agent-skill / core-data-expert

core-data-expert skill

This skill delivers production-grade Core Data guidance for correct, performant stacks, safe cross-context communication, and reliable migrations.

npx playbooks add skill avdlee/core-data-agent-skill --skill core-data-expert

Review the files below or copy the command above to add this skill to your agents.

Files (16)

SKILL.md

4.8 KB

---
name: core-data-expert
description: 'Expert Core Data guidance (iOS/macOS): stack setup, fetch requests & NSFetchedResultsController, saving/merge conflicts, threading & Swift Concurrency, batch operations & persistent history, migrations, performance, and NSPersistentCloudKitContainer/CloudKit sync.'
---
# Core Data Expert

Fast, production-oriented guidance for building **correct**, **performant** Core Data stacks and fixing common crashes.

## Agent behavior contract (follow these rules)

1. Determine OS/deployment target when advice depends on availability (iOS 14+/17+ features, etc.).
2. Identify the context type before proposing fixes: **view context (UI)** vs **background context (heavy work)**.
3. Recommend `NSManagedObjectID` for cross-context/cross-task communication; **never pass `NSManagedObject` instances** across contexts.
4. Prefer lightweight migration when possible; use staged migration (iOS 17+) for complex changes.
5. When recommending batch operations, verify persistent history tracking is enabled (often required for UI updates).
6. For CloudKit integration, remind developers that **Production schema is immutable**.
7. Reference WWDC/external resources sparingly; prefer this skill’s `references/`.

## First 60 seconds (triage template)

- **Clarify the goal**: setup, bugfix, migration, performance, CloudKit?
- **Collect minimal facts**:
  - platform + deployment target
  - store type (SQLite / in-memory) and whether CloudKit is enabled
  - context involved (view vs background) and whether Swift Concurrency is in use
  - exact error message + stack trace/logs
- **Branch immediately**:
  - threading/crash → focus on context confinement + `NSManagedObjectID` handoff
  - migration error → identify model versions + migration strategy
  - batch ops not updating UI → persistent history tracking + merge pipeline

## Routing map (pick the right reference fast)

- **Stack setup / merge policies / contexts** → `references/stack-setup.md`
- **Saving patterns** → `references/saving.md`
- **Fetch requests / list updates / aggregates** → `references/fetch-requests.md`
- **Traditional threading (perform/performAndWait, object IDs)** → `references/threading.md`
- **Swift Concurrency (async/await, actors, Sendable, DAOs)** → `references/concurrency.md`
- **Batch insert/delete/update** → `references/batch-operations.md`
- **Persistent history tracking + “batch ops not updating UI”** → `references/persistent-history.md`
- **Model configuration (constraints, validation, derived/composite, transformables)** → `references/model-configuration.md`
- **Schema migration (lightweight/staged/deferred)** → `references/migration.md`
- **CloudKit integration & debugging** → `references/cloudkit-integration.md`
- **Performance profiling & memory** → `references/performance.md`
- **Testing patterns** → `references/testing.md`
- **Terminology** → `references/glossary.md`

## Common errors → next best move

- **“Failed to find a unique match for an NSEntityDescription”** → `references/testing.md` (shared `NSManagedObjectModel`)
- **`NSPersistentStoreIncompatibleVersionHashError`** → `references/migration.md` (versioning + migration)
- **Cross-context/threading exceptions** (e.g. delete/update from wrong context) → `references/threading.md` and/or `references/concurrency.md` (use `NSManagedObjectID`)
- **Sendable / actor-isolation warnings around Core Data** → `references/concurrency.md` (don’t “paper over” with `@unchecked Sendable`)
- **`NSMergeConflict` / constraint violations** → `references/model-configuration.md` + `references/stack-setup.md` (constraints + merge policy)
- **Batch operations not updating UI** → `references/persistent-history.md` + `references/batch-operations.md`
- **CloudKit schema/sync issues** → `references/cloudkit-integration.md`
- **Memory grows during fetch** → `references/performance.md` + `references/fetch-requests.md`

## Verification checklist (when changing Core Data code)

- Confirm the context matches the work (UI vs background).
- Ensure `NSManagedObject` instances never cross contexts; pass `NSManagedObjectID` instead.
- If using batch ops, confirm persistent history tracking + merge pipeline.
- If using constraints, confirm merge policy and conflict resolution strategy.
- If performance-related, profile with Instruments and validate fetch batching/limits.

## Reference files

- `references/_index.md` (navigation)
- `references/stack-setup.md`
- `references/saving.md`
- `references/fetch-requests.md`
- `references/threading.md`
- `references/concurrency.md`
- `references/batch-operations.md`
- `references/persistent-history.md`
- `references/model-configuration.md`
- `references/migration.md`
- `references/cloudkit-integration.md`
- `references/performance.md`
- `references/testing.md`
- `references/glossary.md`

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

How do I pass objects between background and UI work safely?

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.