swiftdata-migration-writer skill

Overview

This skill generates SwiftData migration logic that moves settings and small preference data from UserDefaults into SwiftData entities for the Leavn app. It focuses on preserving user data, performing validation, and providing rollback and archival steps to keep migrations safe and reversible. The output is ready-to-integrate Swift migration methods and usage notes for calling them on app start.

How this skill works

The skill inspects declared SwiftData entities and a provided mapping of UserDefaults keys to entity fields, then writes an async migration method per entity that reads UserDefaults, validates values, creates or updates SwiftData objects, archives or removes old keys, and marks the migration as complete. It includes rollback hooks and simple validation logic so corrupted or partially-applied migrations can be detected and reversed. The generated code integrates into a PreferencesStore extension and includes guidance for invoking migrations on first load and for writing tests.

When to use it

• When introducing SwiftData entities that should replace existing UserDefaults keys
• When you need to preserve user preferences during a data model transition
• When you want safe, idempotent migration code that marks progress and supports rollback
• When onboarding an app update that changes persistence strategy from UserDefaults to SwiftData

Best practices

• Map each UserDefaults key explicitly to a single SwiftData field and document required transformations
• Validate each migrated value and skip or rollback on invalid input to avoid partial corruption
• Archive old keys (e.g., move to a namespaced key) instead of immediate deletion for recovery
• Mark migrations with a persistent flag to ensure idempotence and avoid repeated work
• Write unit and integration tests that simulate success, validation failures, and rollbacks

Example use cases

• Migrate onboarding-completion flag and last-seen tutorial index into a UserPreferences SwiftData entity
• Move theme, text-size, and notification preferences into a persistent SwiftData store with versioned migrations
• Preserve complex preference objects by validating and transforming legacy keys into nested SwiftData fields
• Create migration that archives old keys under archived.userdefaults.<migration> for audit and rollback

FAQ