Agent-Skills.md

Agent Skills: Data & Persistence

Use when working with ANY data persistence, database, storage, CloudKit, migration, or serialization. Covers SwiftData, Core Data, GRDB, SQLite, CloudKit sync, file storage, Codable, migrations.

UncategorizedID: charleswiltgen/axiom/axiom-data

Repository

charleswiltgen/axiom
CharlesWiltgenLicense: MIT
1,03279

Install this agent skill to your local

pnpm dlx add-skill https://github.com/CharlesWiltgen/Axiom/tree/HEAD/axiom-codex/skills/axiom-data

Skill Files

Browse the full folder contents for axiom-data.

Download Skill

Loading file tree…

axiom-codex/skills/axiom-data/SKILL.md

Skill Metadata

Name
axiom-data
Description
Use when working with ANY data persistence, database, storage, CloudKit, migration, or serialization. Covers SwiftData, Core Data, GRDB, SQLite, CloudKit sync, file storage, Codable, migrations.

Data & Persistence

You MUST use this skill for ANY data persistence, database, storage, CloudKit, or serialization work.

When to Use

Use this skill when working with:

  • Databases (SwiftData, Core Data, GRDB, SQLiteData)
  • Schema migrations
  • CloudKit sync
  • File storage (iCloud Drive, local storage)
  • Data serialization (Codable, JSON)
  • Storage strategy decisions
  • Keychain / secure credential storage
  • Encryption, signing, key management (CryptoKit)

Quick Reference

| Symptom / Task | Reference | |----------------|-----------| | SwiftData @Model, @Query, ModelContext, sectioned queries / ResultsObserver / @Attribute(.codable) / dynamic compound predicates (OS27) | See skills/swiftdata.md | | SwiftData schema migration, VersionedSchema | See skills/swiftdata-migration.md | | SwiftData migration crashes, data loss | See skills/swiftdata-migration-diag.md | | Migrating from Realm to SwiftData | See skills/realm-migration-ref.md | | SwiftData vs SQLiteData decision | See skills/sqlitedata-migration.md | | GRDB queries, ValueObservation, DatabaseMigrator | See skills/grdb.md | | GRDB performance, indexes, EXPLAIN QUERY PLAN, cursors | See skills/grdb-performance.md | | Full-text search (FTS5) in GRDB or SQLiteData | See skills/sqlite-fts-ref.md | | Storing or querying JSON inside a SQLite column (JSON1, JSONB) | See skills/sql-json-ref.md | | GRDB shared across app + widget/extension (App Group) | See skills/grdb-app-groups.md | | SQLiteData @Table, CRUD, SyncEngine | See skills/sqlitedata.md | | SQLiteData advanced patterns, CTEs, views | See skills/sqlitedata-ref.md | | Core Data stack, relationships, concurrency | See skills/core-data.md | | Core Data migration crashes, thread errors | See skills/core-data-diag.md | | ANY schema migration safety | See skills/database-migration.md | | Codable, JSON encoding/decoding | See skills/codable.md | | Cloud sync architecture, offline-first | See skills/cloud-sync.md | | CloudKit, CKSyncEngine, CKRecord | See skills/cloudkit-ref.md | | iCloud Drive, ubiquitous containers | See skills/icloud-drive-ref.md | | Cloud sync errors, conflict resolution | See skills/cloud-sync-diag.md | | Storage strategy, where to store data | See skills/storage.md | | Storage issues, files disappeared | See skills/storage-diag.md | | Storage management, disk pressure | See skills/storage-management-ref.md | | Keychain / secure credential storage | See axiom-security (skills/keychain.md) | | Keychain errors (errSecDuplicateItem) | See axiom-security (skills/keychain-diag.md) | | Keychain API reference | See axiom-security (skills/keychain-ref.md) | | Encryption / signing / key management | See axiom-security (skills/cryptokit.md) | | CryptoKit API reference | See axiom-security (skills/cryptokit-ref.md) | | File protection, NSFileProtection | See axiom-security (skills/file-protection-ref.md) | | tvOS data persistence (no local storage) | See axiom-swift (skills/tvos.md) | | tvOS + CloudKit SyncEngine | See skills/sqlitedata.md |

Automated Scanning

Core Data audit → Launch core-data-auditor agent or /axiom:audit core-data (safety violations, architectural gaps — migration options, thread-confinement, N+1 queries, merge policies, context isolation) Codable audit → Launch codable-auditor agent or /axiom:audit codable (safety violations, semantic gaps — try? swallowing errors, JSONSerialization, date handling, silent field drops, wrapper-hidden fallbacks, cross-file strategy drift, enum future-case crashes) iCloud audit → Launch icloud-auditor agent or /axiom:audit icloud (entitlement checks, file coordination, incomplete CKError matrix coverage, missing account-change observation, polling vs CKSubscriptions, SwiftData + CloudKit unsupported features, compound risks like uncoordinated I/O across extensions) Storage audit → Launch storage-auditor agent or /axiom:audit storage (wrong file locations, missing backup exclusions, sensitive data on disk vs Keychain, missing App Group containers, unbounded cache growth, orphan files, compound risks like user data in tmp/ + critical content) Database schema audit → Launch database-schema-auditor agent or /axiom:audit database-schema (unsafe ALTER TABLE, DROP operations, missing idempotency, FK constraints declared but not enforced, incomplete upgrade paths, compound risks like INSERT OR REPLACE on FK-referenced tables) GRDB performance audit → Launch grdb-performance-auditor agent or /axiom:audit grdb-performance (raw SQL string interpolation, missing FK indexes in raw SQL, missing PRAGMA optimize for raw-GRDB apps, journal mode mismatch for app-group DBs, missing observesSuspensionNotifications for shared DBs, prefix-redundant indexes in raw SQL, legacy Record subclass) SwiftData audit → Launch swiftdata-auditor agent or /axiom:audit swiftdata (struct models, missing schema registration, array relationships without defaults, background context misuse, N+1 patterns, stale predicates, CloudKit conformance gaps, compound risks like struct model + array relationship)

Decision Tree

  1. SwiftData? → skills/swiftdata.md, skills/swiftdata-migration.md
  2. Core Data? → skills/core-data.md, skills/core-data-diag.md
  3. GRDB? → skills/grdb.md 3a. GRDB perf, slow query, schema design for perf? → skills/grdb-performance.md 3b. FTS5 (full-text search, any layer)? → skills/sqlite-fts-ref.md 3c. DB shared across app + extension/widget/Live Activity? → skills/grdb-app-groups.md
  4. SQLiteData? → skills/sqlitedata.md, skills/sqlitedata-ref.md
  5. ANY schema migration? → skills/database-migration.md (ALWAYS — prevents data loss)
  6. Realm migration? → skills/realm-migration-ref.md
  7. SwiftData vs SQLiteData? → skills/sqlitedata-migration.md
  8. Cloud sync architecture? → skills/cloud-sync.md
  9. CloudKit? → skills/cloudkit-ref.md
  10. iCloud Drive? → skills/icloud-drive-ref.md
  11. Cloud sync errors? → skills/cloud-sync-diag.md
  12. Codable/JSON serialization? → skills/codable.md
  13. File storage strategy? → skills/storage.md, skills/storage-diag.md, skills/storage-management-ref.md
  14. File protection? → See axiom-security (skills/file-protection-ref.md)
  15. Keychain / storing tokens, passwords, secrets securely? → See axiom-security (skills/keychain.md), See axiom-security (skills/keychain-diag.md), See axiom-security (skills/keychain-ref.md)
  16. SecItem errors (errSecDuplicateItem, errSecItemNotFound, errSecInteractionNotAllowed)? → See axiom-security (skills/keychain-diag.md)
  17. Encryption, signing, Secure Enclave, CryptoKit? → See axiom-security (skills/cryptokit.md), See axiom-security (skills/cryptokit-ref.md)
  18. Quantum-secure cryptography, HPKE, ML-KEM? → See axiom-security (skills/cryptokit.md)
  19. Want Core Data safety scan? → core-data-auditor (Agent)
  20. Want Codable anti-pattern scan? → codable-auditor (Agent)
  21. Want iCloud sync audit? → icloud-auditor (Agent)
  22. Want storage location audit? → storage-auditor (Agent)
  23. Want database schema/migration safety scan? → database-schema-auditor (Agent) 23a. Want GRDB performance/app-group scan? → grdb-performance-auditor (Agent)
  24. Want SwiftData code audit? → swiftdata-auditor (Agent)
  25. tvOS data persistence? → See axiom-swift (skills/tvos.md) (CRITICAL: no persistent local storage) + skills/sqlitedata.md (CloudKit SyncEngine)
  26. SwiftData @MainActor / background context threading? → /skill axiom-concurrency
  27. Structured data generation with Foundation Models? → /skill axiom-ai

Sync patterns

  • HealthKit anchored/observer queries as a generalizable change-tracking pattern → See axiom-health (skills/sync-and-background.md)

Anti-Rationalization

| Thought | Reality | |---------|---------| | "Just adding a column, no migration needed" | Schema changes without migration crash users. database-migration prevents data loss. | | "I'll handle the migration manually" | Manual migrations miss edge cases. database-migration covers rollback and testing. | | "Simple query, I don't need the skill" | Query patterns prevent N+1 and thread-safety issues. The skill has copy-paste solutions. | | "CloudKit sync is straightforward" | CloudKit has 15+ failure modes. cloud-sync-diag diagnoses them systematically. | | "I know Codable well enough" | Codable has silent data loss traps (try? swallows errors). codable skill prevents production bugs. | | "I'll use local storage on tvOS" | tvOS has NO persistent local storage. System deletes Caches at any time. See axiom-swift (skills/tvos.md) for the iCloud-first pattern. | | "UserDefaults is fine for this token" | UserDefaults is unencrypted, backed up to iCloud, and visible to MDM profiles. One audit catches it. keychain stores tokens securely. | | "I'll encrypt it myself with CommonCrypto" | CryptoKit replaced CommonCrypto's buffer-management nightmares with one-line APIs. cryptokit prevents misuse. |

Critical Pattern: Migrations

ALWAYS read skills/database-migration.md when adding/modifying database columns.

This prevents:

  • "FOREIGN KEY constraint failed" errors
  • "no such column" crashes
  • Data loss from unsafe migrations

Example Invocations

User: "I need to add a column to my SwiftData model" → Read: skills/database-migration.md (critical - prevents data loss)

User: "How do I query SwiftData with complex filters?" → Read: skills/swiftdata.md

User: "CloudKit sync isn't working" → Read: skills/cloud-sync-diag.md

User: "Should I use SwiftData or SQLiteData?" → Read: skills/sqlitedata-migration.md

User: "Check my Core Data code for safety issues" → Launch: core-data-auditor agent

User: "Scan for Codable anti-patterns before release" → Launch: codable-auditor agent

User: "Audit my iCloud sync implementation" → Launch: icloud-auditor agent

User: "Check if my files are stored in the right locations" → Launch: storage-auditor agent

User: "Audit my database migrations for safety" → Launch: database-schema-auditor agent

User: "How do I make my GRDB queries faster?" → Read: skills/grdb-performance.md

User: "Add search to my GRDB-backed app" / "Add search to SQLiteData app" → Read: skills/sqlite-fts-ref.md

User: "My widget needs to read the same database as the app" → Read: skills/grdb-app-groups.md

User: "My widget shows stale data from the database" → Read: skills/grdb-app-groups.md

User: "Audit my GRDB code for performance issues" → Launch: grdb-performance-auditor agent

User: "Check my SwiftData models for issues" → Launch: swiftdata-auditor agent

User: "How do I persist data on tvOS?" → Invoke: See axiom-swift (skills/tvos.md) + Read: skills/sqlitedata.md

User: "My tvOS app loses data between launches" → Invoke: See axiom-swift (skills/tvos.md)

User: "How do I store an auth token securely?" → Invoke: See axiom-security (skills/keychain.md)

User: "errSecDuplicateItem but I checked and the item doesn't exist" → Invoke: See axiom-security (skills/keychain-diag.md)

User: "How do I encrypt data with AES in Swift?" → Invoke: See axiom-security (skills/cryptokit.md)

User: "I need to sign data with the Secure Enclave" → Invoke: See axiom-security (skills/cryptokit.md)

User: "What's ML-KEM and should I use it?" → Invoke: See axiom-security (skills/cryptokit.md)