Update icp-cli and motoko skills for mops-build-based Motoko recipe (v5)

[marc0olo]

Background

The Motoko recipe in icp-cli-recipes is being rewritten to delegate compilation from direct moc invocation to mops build (see dfinity/icp-cli-recipes#26). This is a breaking change (v4 → v5): main, candid, and args are removed from icp.yaml; they move to a new [canisters.<name>] section in mops.toml. The recipe now takes a single name param matching the [canisters] key.

Both the icp-cli and motoko skills document the old configuration and need to be updated once the new recipe version is released.

Blocked on: dfinity/icp-cli-recipes#26 being merged and a new recipe version (v5.x) released.
Templates follow-up tracked in: dfinity/icp-cli-templates#27.

---

Changes needed in skills/icp-cli/SKILL.md

1. Motoko canister configuration example

Current:

canisters:
  - name: backend
    recipe:
      type: "@dfinity/motoko@v4.1.0"
      configuration:
        main: src/backend/main.mo
        candid: backend.did  # optional — if specified, file must exist (auto-generated when omitted)

Replace with (split across icp.yaml and mops.toml):

# icp.yaml
canisters:
  - name: backend
    recipe:
      type: "@dfinity/motoko@v5.0.0"
      configuration:
        name: backend  # must match [canisters] key in mops.toml

# mops.toml
[toolchain]
moc = "1.8.2"

[canisters.backend]
main = "src/backend/main.mo"
candid = "backend.did"  # optional — auto-generated when omitted

2. Available recipes table

Current Motoko row:

| Motoko | `@dfinity/motoko@v4.1.0` | `main` | `candid`, `args`, `shrink`, `compress` |

Updated:

| Motoko | `@dfinity/motoko@v5.0.0` | `name` | `shrink`, `compress`, `metadata` |

(candid and args are no longer recipe params — they move to mops.toml)

3. Prerequisites section

The current text says: "a mops.toml at the project root with the Motoko compiler version [...] The @dfinity/motoko recipe uses this to resolve the compiler. Without mops.toml, the recipe fails because moc is not found."

Update to: mops.toml now also needs a [canisters] section. The name param in the recipe must exactly match a key in [canisters]. If the key is missing or mismatched, mops build fails with:

No Motoko canisters found in mops.toml configuration

4. Pitfall 15 — mops.toml placement

The pitfall currently describes the v4 error: "When mops.toml is not found, mops toolchain bin moc outputs an error instead of a path, causing a cryptic sh: Error:: command not found build failure."

With v5 using mops build, the failure mode changes. Update the error description to match the new recipe's error output.

5. Pitfall 16 — Candid generation with recipes

The Motoko section currently says:

If candid is omitted: the recipe auto-generates the .did file from the compiled WASM (via candid-extractor for Rust, moc for Motoko).

Motoko — use moc directly with the --idl flag:

$(mops toolchain bin moc) --idl $(mops sources) -o backend/backend.did backend/app.mo

With v5, mops build generates the Candid file automatically (placed in .mops/.build/). The manual moc --idl command is still valid for generating a .did to commit, but the context changes:

• candid is no longer a recipe param in icp.yaml — it lives in mops.toml under [canisters.<name>]
• To commit a .did file for use with @icp-sdk/bindgen, specify candid in mops.toml, not in icp.yaml

6. New pitfall: missing [canisters] section in mops.toml

Add a pitfall for the new failure mode introduced by v5:

Missing or mismatched [canisters] in mops.toml — the v5 recipe requires a [canisters.<name>] entry in mops.toml where <name> exactly matches the name parameter in icp.yaml. A mismatch or missing section produces:

No Motoko canisters found in mops.toml configuration

---

Changes needed in skills/motoko/SKILL.md

1. Prerequisites mops.toml example

The current example does not include [canisters]. Since mops build (used by the v5 recipe) requires a [canisters.<name>] section, add a note and expand the example:

Current:

[toolchain]
moc = "1.7.0"

[dependencies]
core = "2.3.1"

[moc]
args = ["--default-persistent-actors", "-W=M0236,M0237,M0223"]

Add:

[canisters.backend]
main = "src/main.mo"
# candid = "backend.did"  # optional; specify to commit a .did file for bindgen

With a note that when using the icp-cli @dfinity/motoko@v5+ recipe, this section is required and the key must match the name param in icp.yaml.

---

Migration summary (for skill bodies and possibly a new pitfall)

Before (icp.yaml, v4)	After (mops.toml, v5)
main: src/main.mo	[canisters.backend] main = "src/main.mo"
candid: backend.did	[canisters.backend] candid = "backend.did"
args: --incremental-gc	[canisters.backend] args = ["--incremental-gc"]
(no equivalent)	name: backend added to recipe configuration