swiftdata-expert-skill
Get specialized guidance on building robust SwiftData architectures for Swift projects. This skill covers schema design, safe concurrency patterns, migration strategies, and CloudKit synchronization—all tailored for AI coding assistants working with SwiftData-first applications.
SwiftData Expert Skill recommends establishing a clear persistence architecture by configuring ModelContainer with appropriate configurations for your deployment target. Use ModelActor for thread-safe operations, maintain separate contexts for background tasks, and leverage @Query for reactive UI binding. Design your schema with proper relationships using @Relationship, apply appropriate delete rules (cascade vs. nullify), and implement unique constraints via indexing. Store history tokens persistently for efficient CloudKit sync and batch operations. Always validate data consistency before and after migrations.
AI-generated summary based on this skill's SKILL.md
Install
vanab/SwiftData-agent-skill/swiftdata-expert-skill
git clone https://github.com/vanab/SwiftData-agent-skill
cp -r SwiftData-agent-skill/swiftdata-expert-skill ~/.claude/skills/swiftdata-expert-skillFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
What are swiftdata persistence architecture best practices?
SwiftData Expert Skill recommends establishing a clear persistence architecture by configuring ModelContainer with appropriate configurations for your deployment target. Use ModelActor for thread-safe operations, maintain separate contexts for background tasks, and leverage @Query for reactive UI binding. Design your schema with proper relationships using @Relationship, apply appropriate delete rules (cascade vs. nullify), and implement unique constraints via indexing. Store history tokens persistently for efficient CloudKit sync and batch operations. Always validate data consistency before and after migrations.
How do you set up swiftdata modelcontainer in swiftui?
SwiftData Expert Skill guides you to initialize ModelContainer in your app's main entry point using @main. Create the container with your model types and optional configurations, then attach it to the SwiftUI environment via .modelContainer(container). For multi-window or app group scenarios, specify custom file URLs and container options. Use @Environment(\.modelContext) in views to access the main context, and @Query for fetching data with automatic refresh. Handle initialization errors gracefully and consider lazy initialization for complex setups.
How should you plan a swiftdata migration for schema changes?
SwiftData Expert Skill emphasizes versioning your schema incrementally. Define migration stages using VersionedSchema, create lightweight migrations for simple changes (adding optional fields, renaming), and implement custom migrations for complex transformations. Test migrations on production-like data before deployment. Use history tokens to track changes across versions. For major schema overhauls, consider a phased rollout where old and new schemas coexist briefly. Always back up user data and provide clear error messaging if migration fails.
What is the recommended swiftdata cloudkit sync configuration?
SwiftData Expert Skill advises configuring CloudKit sync by enabling iCloud sync in ModelConfiguration with isCloudKitEnabled: true. Set up app groups container strategy for cross-process sharing and ensure proper entitlements. Implement persistent history token storage to track synced changes efficiently. Handle network failures gracefully with retry logic and conflict resolution policies. Monitor sync status and provide user feedback. For widget or app extension access, use shared containers and validate that CloudKit schema matches your model definitions.
Why does debugging swiftdata show fetch returns empty results?
SwiftData Expert Skill identifies common causes: incorrect ModelContext usage (wrong actor/thread), missing @Query binding in views, predicate logic errors, or data not yet persisted. Verify the ModelContainer is properly initialized and attached to the environment. Check that your Predicate syntax matches your model's properties. Use print debugging or Xcode's Core Data debugger to inspect the store directly. Ensure relationships are properly loaded and that delete rules haven't unexpectedly removed data. Validate that CloudKit sync hasn't filtered results due to permissions.
How do you safely migrate from Core Data to SwiftData?
SwiftData Expert Skill recommends a coexistence strategy: run both stacks in parallel during transition, map Core Data entities to SwiftData models, and gradually migrate user data. Use ModelMigrationPlan to handle schema evolution. Implement a one-time migration routine that reads from Core Data and writes to SwiftData, then verify data integrity. Keep Core Data stack active as a fallback until migration is complete and tested in production. Document the migration path and provide rollback procedures. Monitor for data loss and sync issues throughout the transition period.
SKILL.md
rendered from the published skill — quoted content, verbatim
SwiftData Expert Skill
Overview
Use this skill to build, review, and harden SwiftData persistence architecture with Apple-documented patterns from iOS 17 through current updates. Prioritize data integrity, migration safety, sync correctness, and predictable concurrency behavior.
Agent Behavior Contract (Follow These Rules)
- Identify the minimum deployment target before recommending APIs (notably
#Index,#Unique,HistoryDescriptor,DataStore, inheritance examples). - Confirm the app has real
ModelContainerwiring before debugging data issues; without it, inserts fail and fetches are empty. - Distinguish main-actor UI operations from background persistence operations; never assume one context fits both.
- Treat
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 11 files
swiftdata-expert-skill/SKILL.md
swiftdata-expert-skill/references/cloudkit-sync.md
swiftdata-expert-skill/references/concurrency-and-actors.md
swiftdata-expert-skill/references/core-data-adoption.md
swiftdata-expert-skill/references/implementation-playbooks.md
swiftdata-expert-skill/references/migrations-and-history.md
swiftdata-expert-skill/references/model-context-and-lifecycle.md
swiftdata-expert-skill/references/modeling-and-schema.md
swiftdata-expert-skill/references/querying-and-fetching.md
swiftdata-expert-skill/references/relationships-and-inheritance.md
swiftdata-expert-skill/references/troubleshooting-and-updates.md