home / skills / willsigmon / sigstack / userdefaults-migrator

userdefaults-migrator skill

/plugins/app-dev/skills/userdefaults-migrator

This skill helps migrate UserDefaults to SwiftData by locating usage, creating entities, updating to PreferencesStore, and archiving keys for a single source

npx playbooks add skill willsigmon/sigstack --skill userdefaults-migrator

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

Files (1)

SKILL.md

640 B

---
name: UserDefaults Migrator
description: Find UserDefaults.standard usage in Leavn, migrate to PreferencesStore/SwiftData, create entities, ensure single source of truth
allowed-tools: Read, Write, Edit, Grep
---

# UserDefaults Migrator

Migrate UserDefaults to SwiftData:

1. **Find usage**: `grep -r "UserDefaults.standard"`
2. **Categorize**:
   - Keep: Tests, debug flags, widgets
   - Migrate: User preferences, stats, settings

3. **Create entity if needed**
4. **Update code to use PreferencesStore**
5. **Write migration logic**
6. **Archive old keys**

Use when: UserDefaults cleanup, preference migration, SwiftData entities

Overview

This skill scans a Swift codebase for UserDefaults.standard usage and migrates selected keys to a SwiftData-backed PreferencesStore with a single source of truth. It automates classification, entity creation, migration logic, and archiving of legacy keys to preserve data and avoid duplication. The goal is a predictable, testable preferences layer and fewer scattered defaults across the app.

How this skill works

The tool greps the repository for UserDefaults.standard occurrences and categorizes each usage into keep-or-migrate buckets (tests, debug flags, widgets vs. user preferences, settings, stats). For migratable items it scaffolds SwiftData entities and a PreferencesStore wrapper, inserts migration code to copy legacy values, and replaces usages with the new API. It also writes archival logic for old keys to avoid accidental reuse.

When to use it

When cleaning up scattered UserDefaults access before a SwiftData migration
When consolidating app preferences into a single source of truth
Before shipping a major release that changes preference storage
When adding typed, testable preference APIs for new features
When auditing legacy keys to prevent silent data loss

Best practices

Run a full grep for UserDefaults.standard and review each hit manually before migrating
Keep non-user data (tests, debug flags, widgets) in UserDefaults unless explicitly required to move
Create well-named SwiftData entities and typed properties to replace raw keys
Implement idempotent migration logic so repeated runs are safe
Archive or namespace old keys instead of deleting them immediately to support rollbacks

Example use cases

Migrate theme, notification, and privacy preferences from UserDefaults to a SwiftData PreferencesStore
Consolidate daily usage stats and counters into SwiftData entities and stop storing them in UserDefaults
Replace ad-hoc boolean flags in multiple files with a single PreferencesStore API
Add a migration step during app launch that moves legacy keys and sets an archived flag
Audit a codebase to find forgotten UserDefaults usage before enabling cloud sync

FAQ

Will this remove keys automatically?

No — it migrates values and archives old keys by renaming or flagging them so you can restore if needed.

Can I migrate only a subset of keys?

Yes — the tool categorizes usages and you choose which groups to migrate; keep categories like tests and widgets out of migration.

Is migration idempotent?

Migration logic is designed to be idempotent: copied values are only moved once and archived keys prevent re-migration.