doc(skills): refine agent skills from icskills PR 183 feedback#6083
Merged
doc(skills): refine agent skills from icskills PR 183 feedback#6083
Conversation
Pulls in the genuinely missing content surfaced by dfinity/icskills#183 and refines it during local review. migrating-motoko-enhanced - Replace older `[canisters.backend].args = ["--enhanced-migration=..."]` pattern with the modern `[canisters.backend.migrations]` block (matches what the mops-cli skill recommends; mops auto-injects `--enhanced-migration` and errors if also set in args). writing-motoko - Add `transient` field semantics (works on let and var) plus M0218 warning on `stable var`. - Add M0220 explanation for `--default-persistent-actors`. - New Pitfalls section: M0141 (types belong in types.mo, with a whois-function example to avoid the field-initializer dilemma) and always-parenthesize-variant-tag-arguments. - New Reserved Keywords section listing all 53 reserved words sourced from src/mo_frontend/source_lexer.mll. - Single consolidated heads-up that under `--enhanced-migration` actor fields cannot have initializers. - Error-pattern table: add M0220, M0141, M0218 rows; generalise the `unexpected token 'label'` row to any keyword. writing-motoko/examples.md - Single heads-up at the top about field-initializer constraint under enhanced migration. Co-authored-by: Cursor <cursoragent@cursor.com>
The "When to Use" section still mentioned the older `--enhanced-migration=migrations` args pattern, inconsistent with the mops.toml setup section earlier in the same file. Co-authored-by: Cursor <cursoragent@cursor.com>
Contributor
|
|
||
| Complete working examples demonstrating modern Motoko patterns. All examples verified with moc 1.5.0. | ||
|
|
||
| > **Heads-up — enhanced migration:** the actor examples below declare fields with initializers (`let users = List.empty(); var nextId = 0;`). Under `--enhanced-migration`, actor fields **cannot** have initializers — declare them as `var nextId : Nat;` and set initial values in the first migration file. See the `migrating-motoko-enhanced` skill. |
Contributor
There was a problem hiding this comment.
first migration file? or should we make it more specific like the migration file that introduces them?
| - Enhanced orthogonal persistence (state persists without `stable`) | ||
| - Principled architecture — `types.mo`, `lib/`, `mixins/`, `main.mo` | ||
| **For actor upgrades/migrations:** load `migrating-motoko` for inline migration or `migrating-motoko-enhanced` for multi-migration with `--enhanced-migration`. | ||
| **For actor upgrades/migrations:** load `migrating-motoko` for inline migration or `migrating-motoko-enhanced` for multi-migration with `--enhanced-migration`. Under `--enhanced-migration`, actor fields **cannot** have initializers — declare them as `var x : T;` and set initial values in the first migration. The actor examples in this skill use initializers and would need adjustment for enhanced-migration projects. |
alexandru-uta
approved these changes
May 5, 2026
Contributor
alexandru-uta
left a comment
alexandru-uta
left a comment
There was a problem hiding this comment.
looks ok, maybe rephrase the "first migration function" phrasing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Pulls in the genuinely missing content surfaced by dfinity/icskills#183 and refines it during local review. Three skill files are touched; nothing renamed, no frontmatter restructure, no reference-file split.
What changes for agents
writing-motokotransientfield semantics — works on bothletandvar, withstable var(M0218) warning.--default-persistent-actorsisn't set.types.moextraction (consistent with the architecture pattern earlier in the skill); shows awhoisfunction example so there's no field-initializer ambiguity.src/mo_frontend/source_lexer.mll. Replaces the previous single-keyword (label) note in the error table with a generalised entry pointing here.--enhanced-migration, actor fields cannot have initializers — declare asvar x : T;and set initial values in the first migration.writing-motoko/examples.mdmigrating-motoko-enhanced[canisters.backend].args = ["--enhanced-migration=migrations"]pattern with the modern[canisters.backend.migrations]block. This matches what themops-cliskill (in the mops repo) already recommends, and mops auto-injects--enhanced-migration— adding it to args causes a mops error.What was deliberately not adopted from icskills#183
writing-motoko→motoko, frontmatter additions (license,compatibility,metadata.*), upstream-sync comment blocks — icskills catalog metadata, not relevant upstream.references/{control-flow,type-conversions}.md) — would be a larger restructure than warranted.migrating-motokoskill changes — purely cosmetic in icskills (rename of "Resources" → "References", added "What This Is").Text.joinparameter order,List.getvsList.at,do ? { }for!, M0145 incomplete-pattern pitfall — judged either belonging in mo:core docs or obvious from the error message.