Core-Data-Agent-Skill

Core Data Agent Skill

Expert guidance for any AI coding tool that supports the Agent Skills open format — safe persistence, performance optimization, and schema migration.

Based on the Core Data Best Practices repo, WeTransfer production apps, and WWDC sessions, distilled into actionable, concise references for agents.

Who this is for

• Teams working with Core Data who need safe defaults and quick triage
• Developers debugging persistence issues, threading errors, or performance problems
• Anyone migrating schemas or integrating CloudKit sync

See also my other skills:

• Swift Concurrency Expert
• SwiftUI Expert
• Swift Testing Expert

How to Use This Skill

Option A: Using skills.sh (recommended)

Install this skill with a single command:

npx skills add https://github.com/avdlee/core-data-agent-skill --skill core-data-expert

For more information, visit the skills.sh platform page.

Then use the skill in your AI agent, for example:

Use the core data skill and analyze the current project for Core Data improvements

Option B: Claude Code Plugin

Personal Usage

To install this Skill for your personal use in Claude Code:

1. Add the marketplace:

   /plugin marketplace add AvdLee/Core-Data-Agent-Skill
   

2. Install the Skill:

   /plugin install core-data-expert@core-data-agent-skill
   

Project Configuration

To automatically provide this Skill to everyone working in a repository, configure the repository’s .claude/settings.json:

{
  "enabledPlugins": {
    "core-data-expert@core-data-agent-skill": true
  },
  "extraKnownMarketplaces": {
    "core-data-agent-skill": {
      "source": {
        "source": "github",
        "repo": "AvdLee/Core-Data-Agent-Skill"
      }
    }
  }
}

When team members open the project, Claude Code will prompt them to install the Skill.

Option C: Manual install

1. Clone this repository.
2. Install or symlink the core-data-expert/ folder following your tool’s official skills installation docs (see links below).
3. Use your AI tool as usual and ask it to use the “core-data-expert” skill for Core Data tasks.

Where to Save Skills

Follow your tool’s official documentation, here are a few popular ones:

• Codex: Where to save skills
• Claude: Using Skills
• Cursor: Enabling Skills

How to verify:

Your agent should reference the triage/playbook in core-data-expert/SKILL.md and jump into the relevant reference file for your error or task.

What This Skill Offers

This skill gives your AI coding tool comprehensive Core Data guidance. It can:

Guide Your Persistence Decisions

• Choose the right stack setup (NSPersistentContainer vs NSPersistentCloudKitContainer)
• Understand when to use view context vs background context
• Navigate merge policies and conflict resolution
• Apply proper context configuration for your use case

Write Thread-Safe Code

• Avoid common threading pitfalls with NSManagedObjectID
• Prevent data races with proper context usage
• Handle cross-context communication correctly
• Use perform vs performAndWait appropriately

Optimize Performance

• Write efficient fetch requests with proper batching and property limiting
• Reduce memory usage with context resets and faulting control
• Use batch operations for large-scale data changes
• Profile with Instruments to identify bottlenecks

Migrate Schemas Safely

• Use lightweight migration for common changes
• Decompose complex migrations with staged migration (iOS 17+)
• Defer expensive cleanup with deferred migration (iOS 14+)
• Handle composite attributes and model versioning

Integrate with CloudKit

• Set up NSPersistentCloudKitContainer correctly
• Design schemas within CloudKit limitations
• Monitor sync with event notifications
• Debug sync issues with system logs

What Makes This Skill Different

Expert Knowledge: Based primarily on the comprehensive SwiftLee Core Data articles and the Core Data Best Practices repository, with additional insights from WWDC sessions. All content reflects real-world experience from production apps like Collect by WeTransfer.

Non-Opinionated: Focuses on industry-standard best practices and compile-time safety, not architectural preferences. Works with any Swift project, coding style, or architecture.

Modern Core Data: Covers the latest features including:

• Composite attributes (iOS 17+)
• Staged migration (iOS 17+)
• Deferred migration (iOS 14+)
• NSBatchInsertRequest improvements (iOS 14+)
• NSPersistentCloudKitContainer patterns

Practical & Concise: Assumes your AI agent is already smart. Focuses on what developers need to know, not what they already understand. Includes code examples for every pattern.

Skill Structure

core-data-expert/
├── SKILL.md                       # Main skill file with decision trees
└── references/
    ├── _index.md                  # Navigation index
    ├── batch-operations.md        # NSBatchInsertRequest, NSBatchDeleteRequest, NSBatchUpdateRequest
    ├── cloudkit-integration.md    # NSPersistentCloudKitContainer, schema design, monitoring
    ├── fetch-requests.md          # Query optimization, NSFetchedResultsController, aggregates
    ├── glossary.md                # Core Data terminology and quick definitions
    ├── migration.md               # Lightweight, staged, and deferred migration strategies
    ├── model-configuration.md     # Constraints, derived attributes, transformables, validation
    ├── performance.md             # Profiling with Instruments, memory management, optimization
    ├── persistent-history.md      # History tracking setup, Observer/Fetcher/Merger/Cleaner
    ├── project-audit.md           # Checklist to discover a project's Core Data setup
    ├── saving.md                  # Conditional saving, hasPersistentChanges, save timing
    ├── stack-setup.md             # NSPersistentContainer setup, merge policies, contexts
    ├── testing.md                 # In-memory stores, shared models, data generators
    └── threading.md               # NSManagedObjectID, perform vs performAndWait, concurrency

Resources

This skill is based primarily on:

• SwiftLee Core Data Articles - Comprehensive articles covering Core Data best practices, performance optimization, and real-world implementations
• Core Data Best Practices GitHub Repository - Working code examples demonstrating Core Data best practices

Additional resources:

• WWDC 2022-10119: Optimize your use of Core Data and CloudKit - Performance optimization and CloudKit integration
• WWDC 2022-10120: Evolve your Core Data schema - Schema migration strategies
• WWDC 2023-10186: What’s new in Core Data - Composite attributes, staged migration, and deferred migration

Contributing

Contributions are welcome! This repository follows the Agent Skills open format, which has specific structural requirements.

We strongly recommend using AI assistance for contributions:

• Use the skill-creator skill with Claude to ensure proper formatting
• This helps maintain the Agent Skills format and ensures your contribution works correctly with AI agents

Please read CONTRIBUTING.md for:

• How to use the skill-creator skill for contributions
• Agent Skills format requirements
• Quality standards and best practices
• Pull request process

This skill is maintained to reflect the latest Core Data best practices and will be updated as the framework evolves.

About the Author

Created by Antoine van der Lee, a Swift expert with years of experience building production apps with Core Data. He developed the Collect by WeTransfer app for over four years and has published numerous articles on Core Data on his blog called SwiftLee.

License

This skill is open-source and available under the MIT License. See LICENSE for details.