feat: add motoko, mops-cli, and migration skills synced from caffeinelabs upstream#183
feat: add motoko, mops-cli, and migration skills synced from caffeinelabs upstream#183
Conversation
…trategy
- Rewrites motoko skill to align with caffeinelabs/motoko 1.7.0: plain
actor {} with --default-persistent-actors flag as the primary style,
transient var for reset-on-upgrade semantics, dot notation for
collection operations (mo:core), and moc >= 1.2.0 compatibility
- Adds mops-cli skill synced from caffeinelabs/mops cli-v2.13.1:
covers mops.toml configuration, mops check, mops toolchain, mops
migrate, mops test, and lintoko integration
- Adds migrating-motoko skill: inline (with migration = ...) syntax for
single-step actor state transformations without --enhanced-migration
- Adds migrating-motoko-enhanced skill: migrations/ directory approach
with --enhanced-migration for multi-step verifiable migration chains
- Creates Motoko category for the three language skills; mops-cli stays
in Infrastructure
- Adds upstream sync strategy to CLAUDE.md: commit-hash pinning,
two-step annotated tag dereference, curl+diff workflow
- Adds evaluation files for all four skills with adversarial cases
- Adds motoko/references/ directory with api-reference, control-flow,
examples, and type-conversions reference files
Add Sections owned by icskills to upstream comment blocks for migrating-motoko, migrating-motoko-enhanced, and mops-cli, listing which content should not be overwritten on upstream syncs. Expand CLAUDE.md sync strategy with a table of change types (cross-references, bug fixes, IC-specific additions vs shared content), and document the planned automated upstream release detection workflow adapted from dfinity/developer-docs.
Skill Validation ReportProject Checks |
Upstream contribution candidatesWhile syncing with `caffeinelabs/motoko` 1.7.0 and `caffeinelabs/mops` cli-v2.13.1, I identified several improvements in our versions that could be contributed back upstream. Flagging them here so we can decide which are worth upstreaming. caffeinelabs/motoko — from
|
| # | Item | Priority | Reason |
|---|---|---|---|
| 1 | mops.toml prerequisites block | High | Prevents misconfigured projects |
| 2 | transient var section + M0218 warning |
High | Common confusion, frequently needed |
| 3 | M0141 / M0145 pitfalls | High | Common agent errors |
| 7 | Enhanced migration [canisters.migrations] pattern |
Medium | The upstream approach works, but ours is safer |
| 4 | do? {} syntax |
Medium | Less common but zero-cost to add |
| 5 | Text.join / List.get vs List.at | Low | Niche enough to be noise in upstream |
| 6 | Runtime.envVar | Low | IC-specific, may not belong upstream |
Happy to draft any of these as PRs to `caffeinelabs/motoko` if we decide they're worth contributing.
Adds .github/workflows/sync-upstream.yml that detects new releases of caffeinelabs/motoko and caffeinelabs/mops, opens a diff PR for manual review. Workflow does not auto-apply changes. Updates CLAUDE.md to reference the actual workflow file and document icskills-owned vs upstream content by change type.
…emove unused has_changes var
…l tag on pagination boundary
skills/skill.schema.json was being extracted by grep and then failing the SKILL.md file test, causing bash -e to exit the step. Add lookahead (?=/) to require a path separator after the dir name, and add || true to the while loop as a belt-and-suspenders guard.
api-reference.md is a static snapshot of versioned library signatures that will silently drift from reality as mo:core evolves. Directing agents to the live mops.one/core reference is more reliable. examples.md, control-flow.md, and type-conversions.md are pattern-based and stable across releases — kept and documented as icskills-owned in the upstream comment block.
… GITHUB_TOKEN GITHUB_TOKEN with contents:write + pull-requests:write is blocked on public dfinity repos (see dfinity/developer-docs#196). Switch both jobs to the pr-automation-bot-public GitHub App token. - Remove elevated permissions blocks from both jobs - Add Create GitHub App Token step (actions/create-github-app-token v3) - Replace secrets.GITHUB_TOKEN with steps.app-token.outputs.token - Move curl auth to GH_TOKEN env var (avoids inline token interpolation) - Update git committer name to pr-automation-bot-public[bot]
…inelabs#6083) ## Summary Pulls in the genuinely missing content surfaced by [dfinity/icskills#183](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-motoko`** - New section: `transient` field semantics — works on both `let` and `var`, with `stable var` (M0218) warning. - New section: M0220 explanation — what happens when `--default-persistent-actors` isn't set. - New **Pitfalls** section (2 items): - M0141 declarations before actor body — recommends `types.mo` extraction (consistent with the architecture pattern earlier in the skill); shows a `whois` function example so there's no field-initializer ambiguity. - Always parenthesize variant tag arguments — written as a positive rule rather than a precedence warning. - New **Reserved Keywords** section listing all 53 reserved words, sourced from `src/mo_frontend/source_lexer.mll`. Replaces the previous single-keyword (`label`) note in the error table with a generalised entry pointing here. - Single consolidated heads-up under Critical Requirements that under `--enhanced-migration`, actor fields cannot have initializers — declare as `var x : T;` and set initial values in the first migration. - Error-pattern table gains M0220, M0141, M0218 rows. **`writing-motoko/examples.md`** - Single heads-up at the top about the same field-initializer constraint, so agents reading examples in isolation aren't surprised. **`migrating-motoko-enhanced`** - Bug fix: replaces the older `[canisters.backend].args = ["--enhanced-migration=migrations"]` pattern with the modern `[canisters.backend.migrations]` block. This matches what the `mops-cli` skill (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 - **Skill rename** `writing-motoko` → `motoko`, **frontmatter additions** (`license`, `compatibility`, `metadata.*`), **upstream-sync comment blocks** — icskills catalog metadata, not relevant upstream. - **Reference-file split** (`references/{control-flow,type-conversions}.md`) — would be a larger restructure than warranted. - **`migrating-motoko` skill changes** — purely cosmetic in icskills (rename of "Resources" → "References", added "What This Is"). - `Text.join` parameter order, `List.get` vs `List.at`, `do ? { }` for `!`, M0145 incomplete-pattern pitfall — judged either belonging in mo:core docs or obvious from the error message. --------- Co-authored-by: Cursor <cursoragent@cursor.com>
1 participant
Summary
motokoskill to align withcaffeinelabs/motoko1.7.0: plainactor {}with--default-persistent-actorsflag as the primary style,transient varfor reset-on-upgrade, dot notation for mo:core collections, moc >= 1.2.0 compatibilitymops-cliskill synced fromcaffeinelabs/mopscli-v2.13.1: mops.toml configuration, mops check (canister name not file path), mops toolchain, mops migrate, mops test, lintoko integrationmigrating-motokoskill: inline(with migration = ...)syntax for single-step actor state transformationsmigrating-motoko-enhancedskill:migrations/directory approach with--enhanced-migrationfor multi-step verifiable migration chainsMotokocategory for the three language skills; mops-cli stays in InfrastructureUpstream diff notes
All four skills are synced from tagged releases and track exact commit SHAs. Sections that icskills owns (not synced from upstream) are documented in each skill's upstream comment block:
motokomigrating-motokomigrating-motoko-enhancedargs = ["--enhanced-migration=..."]is redundant when[canisters.backend.migrations]is configured), Additional Referencesmops-cliEval results
motoko — new/updated eval cases
Eval 1 — Simple actor with counter (eval rubric updated for flag-based style)
Note: This is common knowledge; the eval confirms the rubric accepts both
actor {}(with flag) andpersistent actor.Eval 7 — Transient vs stable semantics (new)
Without skill, agents use
stable varand never mentiontransient varor the flag.Eval 8 — Caffeine to icp-cli: resolving M0220 errors (renamed from "Migration from plain actor to flag-based setup")
Without skill, agents don't know about
--default-persistent-actorsor Caffeine's implicit persistence behavior.migrating-motoko — full suite
Output evals:
Trigger evals: should-trigger 7/7 ✅ | should-not-trigger 7/7 ✅
Notes:
preupgrade/postupgradeMap.mapinstead of dot notationold.users.map(...)— skill improvement opportunitymigrating-motoko-enhanced — full suite
Output evals:
--enhanced-migrationin argsTrigger evals: should-trigger 8/8 ✅ | should-not-trigger 7/7 ✅
Notes:
mops-cli — full suite
Output evals:
Trigger evals: should-trigger 12/12 ✅ | should-not-trigger 8/8 ✅
Notes:
mops init -y,mops toolchain use moc latest, or the correct mops.toml structure