Skills migrating-motoko-actors

📦

migrating-motoko-actors

Name: migrating-motoko-actors
Author: caffeinelabs

v0.2.6 Content revision r1 Safe ⚙️ External commands🌐 Network access📁 Filesystem access

Migrate Motoko Actors With Enhanced Migration Chains

Motoko canister upgrades can fail or lose data when state changes do not match migration inputs and outputs. This skill guides compatible changes, self-contained migrations, and validation for enhanced migration chains.

Supports: Claude Codex Code(CC)

🥈 80 Silver

Install with my Agent

Copy this request to your Agent. It includes the canonical Skill page and manifest.

Agent request

Review the Skillstore skill "migrating-motoko-actors" from https://skillstore.io/skills/caffeinelabs-migrating-motoko-actors.md and its manifest at https://skillstore.io/api/skills/caffeinelabs-migrating-motoko-actors/manifest. Verify the artifact. You may proceed after verification, subject to the environment's own policy.

Your Agent should still show its plan and request any confirmation required by the security policy.

Agent-readable resources

Use these links when an AI agent, crawler, or script needs clean context instead of reading the full page.

Markdown detail GET /skills/caffeinelabs-migrating-motoko-actors.md Signed manifest GET /api/skills/caffeinelabs-migrating-motoko-actors/manifest Signed lockfile GET /api/skills/caffeinelabs-migrating-motoko-actors/lockfile

Test it

Using "migrating-motoko-actors". An enhanced migration project adds an optional assignee field to every stored task.

Expected outcome:

Use an explicit migration that preserves existing task values and initializes each assignee as absent. Extend the pending migration if one already exists.

Using "migrating-motoko-actors". A canister changes a stable numeric field from Nat to Int.

Expected outcome:

This is usually a stable-compatible widening and does not need an explicit migration. Confirm the deployed signature and run the compatibility check.

Using "migrating-motoko-actors". A canister renames artist to artists and changes the value from text to a set.

Expected outcome:

Transform the old text value into a single-item set for the renamed field. Inline both state types and preserve all unrelated fields.

Security Audit

Safe

v1 • 10/2/2026 Open versioned report

All 77 static findings are false positives involving Markdown formatting, legitimate mops validation commands, official documentation links, and Motoko type notation. The relative import example explicitly prohibits project imports rather than performing path traversal. No evidence found of prompt injection, credential access, unauthorized data transmission, or malicious migration intent in the two reviewed files.

Files scanned

397

Lines analyzed

Review items

False positives ignored

Risk Factors

⚙️ External commands (50)

🌐 Network access (2)

SKILL.md:276 SKILL.md:277

📁 Filesystem access (1)

SKILL.md:43

No confirmed security findings were detected by the latest completed static and semantic audit. This does not prove the skill has no side effects.

Audited by: codex

Share & cite this report

Share the versioned assessment report, neutral badge, embed card, and citations. Skillstore reports evidence without deciding whether this Skill is safe.

Open versioned report

Copy report link

https://skillstore.io/skills/caffeinelabs-migrating-motoko-actors/audits/1?utm_source=security_passport&utm_medium=share&utm_campaign=versioned_report

Markdown badge

[![Skillstore security assessment](https://skillstore.io/badges/skills/caffeinelabs-migrating-motoko-actors/security.svg)](https://skillstore.io/skills/caffeinelabs-migrating-motoko-actors?utm_source=security_passport_badge)

HTML badge

<a href="https://skillstore.io/skills/caffeinelabs-migrating-motoko-actors?utm_source=security_passport_badge"><img src="https://skillstore.io/badges/skills/caffeinelabs-migrating-motoko-actors/security.svg" alt="Skillstore security assessment" loading="lazy"></a>

Embed card

<iframe src="https://skillstore.io/embed/skills/caffeinelabs-migrating-motoko-actors.html" title="Skillstore Security Assessment" sandbox="allow-popups allow-popups-to-escape-sandbox" loading="lazy" referrerpolicy="no-referrer" width="420" height="180"></iframe>

Academic citations (APA · BibTeX · CFF)

APA citation

caffeinelabs. (2026). migrating-motoko-actors security audit report (audit version 1) [Author version 0.2.6]. Skillstore. https://skillstore.io/skills/caffeinelabs-migrating-motoko-actors/audits/1

BibTeX citation

@techreport{caffeinelabs-caffeinelabs-migrating-motoko-actors-2026,
  author = {caffeinelabs},
  title = {migrating-motoko-actors security audit report (audit version 1)},
  institution = {Skillstore},
  year = {2026},
  number = {1},
  url = {https://skillstore.io/skills/caffeinelabs-migrating-motoko-actors/audits/1},
  note = {Author version 0.2.6}
}

CITATION.cff

cff-version: 1.2.0
message: "If you use this Skill, cite its author and this versioned security audit report."
title: "migrating-motoko-actors security audit report (audit version 1)"
version: "0.2.6"
type: report
authors:
  - name: "caffeinelabs"
date-released: "2026-10-02"
url: "https://skillstore.io/skills/caffeinelabs-migrating-motoko-actors/audits/1"
identifiers:
  - type: other
    value: "skillstore:caffeinelabs-migrating-motoko-actors:audit:1"
    description: "Skillstore immutable audit report identifier"

Skillstore Score

Why this score Evidence Confidence: Medium

Architecture

100

Maintainability

Content

Community

Spec Compliance

What You Can Build

Understand stable state changes

Classify proposed field changes and identify when an enhanced migration file is necessary.

Write a migration module

Draft self-contained state transformations while preserving unchanged fields and using the existing pending migration.

Review upgrade readiness

Check chain ordering, deployed signatures, intentional data removal, and validation steps before releasing an upgrade.

Try These Prompts

Classify a state change

My project uses enhanced Motoko migrations. Classify these stable field changes as implicit or explicit: [changes]. Explain each decision.

Plan a new field

Add this stable field in my enhanced migration project: [field and type]. Review [existing chain] and propose initialization without modifying applied migrations.

Transform stored records

Using [old fields], [new fields], and [business rules], draft a self-contained Motoko migration. Preserve unchanged state and explain every default and discarded field.

Audit an upgrade plan

Review [migration plan], [deployed signature], and [mops configuration]. Check stable compatibility, chain ordering, pending limits, fresh installation, and data preservation. Propose validation steps.

Best Practices

Derive old state from the preceding migration; use empty state only for a new chain, not a legacy conversion.
Keep applied migrations unchanged and fold new work into the pending file.
Run compatibility checks before building and test the upgrade with representative state.

Avoid

Do not add a migration for a stable-compatible change or an identity transformation.
Do not apply the enhanced-chain initializer rules to plain actors without a migration chain.
Do not import project types into frozen migration files or discard fields unintentionally.

Frequently Asked Questions

When is an explicit migration required?

In enhanced migration projects, use one for renamed, removed, narrowed, transformed, or newly added stable fields.

Can I change field mutability without a migration?

Yes. Changing var to let, or the reverse, is usually stable-compatible.

Where should migration files live?

Read the chain directory in mops.toml. The default location in this guide is src/backend/migrations/.

Why must migration types be inlined?

Project type imports can change and invalidate historical transformations. Inline old and new types; core and mops package imports are permitted.

How do I initialize a new stable field?

Under enhanced migration, declare its type in the actor and supply its value from the migration output. Plain actors follow different initialization rules.

Does this skill deploy my canister?

It does not include a deployment script. It guides migration authoring, compatibility checks, and builds; deployment still requires your project workflow.