modifying-cloudkit-schema

Guides additive-only CloudKit schema changes through schema.ckdb, generated wire structs, and Swift adapters.

1|Updated Apr 5, 2026
One-click install
npx skills add https://github.com/moolah-rocks/moolah-native --skill modifying-cloudkit-schema-moolah-rocks
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: modifying-cloudkit-schema
Source: https://github.com/moolah-rocks/moolah-native/tree/main/.claude/skills/modifying-cloudkit-schema
Command: npx skills add https://github.com/moolah-rocks/moolah-native --skill modifying-cloudkit-schema-moolah-rocks

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? CloudKit Production schemas are additive-only, so deleting or renaming fields incorrectly can permanently break a live app. This Skill enforces the correct workflow for evolving the schema safely: editing the canonical schema.ckdb manifest, regenerating wire structs, updating Swift adapters, and respecting the Production baseline. ## Core Features & Use Cases - Field lifecycle management: Add fields with correct index policies, deprecate fields via // DEPRECATED markers instead of deletion, and handle renames as deprecate-plus-add with read-time migration. - Record type creation: Declare new record types in schema.ckdb, generate wire structs, write CloudKitRecordConvertible adapters, and register them in RecordTypeRegistry. - Error diagnosis: Maps common failures (missing wire-struct members, check-schema-additive violations, cktool import errors) to their root causes and fixes. - Use Case: When a Swift compile error like "value of type 'AccountRecordCloudKitFields' has no member 'foo'" appears, use this Skill to determine whether the field must be added to schema.ckdb or removed from the adapter, then regenerate with just generate. ## Quick Start Ask the AI to add a new field to a CloudKit record type and update the schema, adapter, and round-trip test accordingly.

Frequently Asked Questions about modifying-cloudkit-schema

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new field to a CloudKit record type?▼

Add the field to the RECORD TYPE block in schema.ckdb with the standard index policy, run just generate to regenerate the wire struct, then populate it in the adapter's toCKRecord and fieldValues methods. Finish with a round-trip test and just test.

How do I remove or rename a CloudKit field in production?▼

CloudKit Production schemas are additive-only, so fields cannot be deleted. Add a // DEPRECATED comment above the field in schema.ckdb, regenerate, and remove adapter references. Renames require adding a new field, migrating reads, then deprecating the old one.

Why does my Swift build fail with 'has no member' on a CloudKitFields struct?▼

This error means schema.ckdb does not declare the field the adapter references. Either add the field to the manifest and run just generate, or remove the reference from the adapter. Never edit the generated wire structs directly.

What does a just check-schema-additive failure mean?▼

It means the proposed schema removes a record type, removes a field, changes a field type, or drops an index that exists in Production. Fix it by using // DEPRECATED instead of deletion; never hand-edit schema-prod-baseline.ckdb to bypass the check.

Can I run cktool or promote the CloudKit schema manually?▼

Routine work should go through just commands like just generate and just verify-schema. just promote-schema is reserved for release-tag CI, and cktool should never be invoked directly or forced with --force.