Agent skill · software engineering · caffeinelabs
migrating-motoko-actors
Motoko actor migration and schema evolution with the enhanced migration chain (migrations/). Load when upgrading canisters or changing actor state shape.
Why this skill is useful
Adds specific migration patterns and rules for Motoko actor state management that the AI wouldn't reliably generate on its own.
What it needs
About 10k tokens when loaded. Last updated 2026-08-06.
What this skill does
Motoko Actor Migrations Expert guidance for migrating actor state across canister upgrades with orthogonal persistence. Critical: Never use classical persistence or pre/post upgrade Do not use classical (legacy) persistence or system func preupgrade / system func postupgrade. They are error-prone, can leave canisters stuck if they trap, and do not scale. Also do not use the legacy (with migration = ...) actor-attached syntax. This skill covers mops-managed migrations. When a change requires an explicit migration, write it as a timestamped file in src/backend/migrations/; the chain replays automatically. How stable state is initialized Stable actor fields have no initializers in the actor body. The chain in src/backend/migrations/ is what gives them values: the runtime walks it in lexicographic order, running every file on a fresh install and only the files not yet applied to the canister on an upgrade. When to Use This Skill Planning or implementing a canister upgrade that changes actor state Deciding between implicit vs explicit migration Writing or refactoring a migration function Introducing stable state for the first time (use a NEW migration file with OldActor = {}) Migration Folder Rules All migrations live in src/backend/migrations/. The full chain replays in lexicographic filename order on fresh install; on upgrade, only entries newer than the deployed tail run. (The directory is declared as chain = ... under [canisters.<name>.migrations] in mops.toml; an imported project using a non-default canister name may place it elsewhere — read mops.toml rather than assuming.) At most one pending migration per build (check-limit = 1 in mops.toml). If this build already added a migration file, edit that file to fold in further changes instead of adding another. mops check compares the deployed .most baseline and names the latest pending file to fold into when the limit is exceeded. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills caffeinelabs/migrating-motoko-actors