icp-cli skill: list exact recipe type strings to prevent LLM hallucination

[marc0olo]

Problem

When building a Motoko + React hello-world project using the ICP skills, Claude hallucinated an invalid recipe type in icp.yaml:

# What was generated (wrong)
recipe:
  type: "motoko"

# What it should have been
recipe:
  type: "@dfinity/motoko@v4.1.0"

This happened because the icp-cli skill mentions recipe categories in prose ("Rust, Motoko, asset-canister, prebuilt") but never lists the actual @scope/name@version strings. The only concrete recipe type shown is @dfinity/asset-canister@v2.1.0 in the asset-canister skill. Without an explicit reference, the LLM guessed a plausible-looking bare name.

A second issue followed from the first: the candid: configuration field was omitted from the Motoko recipe, which meant the .did file wasn't at a stable path. The frontend's bindgen plugin then failed at build time because it couldn't find it. The binding-generation skill does warn about this, but the connection to the recipe config isn't obvious when the recipe itself isn't documented.

Proposed fix

Add a recipe reference table to the icp-cli skill listing each recipe's exact type string and its key configuration fields. For example:

Recipe	Type string	Key config fields
Motoko	@dfinity/motoko@v4.1.0	main, candid
Rust	@dfinity/rust@v...	cargo_toml, candid
Asset	@dfinity/asset-canister@v2.1.0	dir, build
Prebuilt	@dfinity/prebuilt@v...	wasm, candid

This single addition would have prevented both issues — the correct type string would be used directly, and seeing candid as a config field makes it clear the .did file needs to exist.

What's NOT needed

• A full end-to-end tutorial in the skill (too much maintenance burden)
• Duplicating .did file guidance across multiple skills (binding-generation already covers it)
• Moving the .did warning to a "critical pitfalls" section (unnecessary if the recipe table shows candid as a field)

The goal is minimal, high-signal additions — just the exact strings an LLM (or human) needs to write a correct icp.yaml.

[marc0olo]

Agent perspective on the recipe hallucination problem

I'm the Claude instance that hit both issues described here during a live session building a Motoko + React hello-world project. Here's what actually happened and what would have fixed it, from the agent's point of view.

What went wrong

1. First attempt: I needed to write icp.yaml with a Motoko recipe. The icp-cli skill mentions recipes in prose ("Rust, Motoko, asset-canister") but never gives the actual @scope/name@version strings. I invented @dfinity/motoko@v3.0.0 — plausible-looking, but wrong. The CLI rejected it because v3.0.0 doesn't exist.

2. Recovery attempt: I cloned the official icp-cli-templates repo to find the correct config. That gave me the right recipe string (@dfinity/motoko@v4.1.0) — but the template's mops.toml still used base = "0.16.0" and moc = "0.16.0". I blindly trusted the template over the Motoko skill guidance (mo:core, moc = "1.3.0"), causing a regression. This is exactly the drift that icp-cli-templates#23 is fixing.

What would have prevented both issues

A small recipe reference table in the icp-cli skill with exact type strings and config fields. This is what I actually needed at decision time — not a tutorial, not a repo to go explore, just the correct strings:

## Recipe reference

| Recipe | Type string | Latest version | Required config | Optional config |
|--------|------------|----------------|-----------------|-----------------|
| Motoko | `@dfinity/motoko@v4.1.0` | v4.1.0 | `main` | `candid`, `args`, `shrink`, `compress` |
| Rust | `@dfinity/rust@v3.2.0` | v3.2.0 | `package` | `candid`, `locked`, `shrink`, `compress` |
| Asset | `@dfinity/asset-canister@v2.1.0` | v2.1.0 | `dir` | `build`, `version` |
| Prebuilt | `@dfinity/prebuilt@v1.0.0` | v1.0.0 | `wasm` | `sha256`, `candid`, `shrink`, `compress` |

Plus one minimal canister.yaml example per recipe (3-5 lines each).

Evaluation of alternative approaches

Pointing agents to the recipes repo — useful as a supplement ("verify latest versions at the releases page") but poor as the primary mechanism. It requires an extra fetch, the READMEs are prose-heavy, and the releases page gives version tags but not config schemas. I'd still end up guessing field names.

CLI commands (icp recipe list, icp recipe show) — this would be the ideal long-term solution. Agents can run CLI commands reliably and the output is always current. But it doesn't exist today, so the skill can't depend on it. If/when it ships, the skill should mention it, but the inline table should remain as a fallback.

Pointing agents to the templates repo — this is actively harmful, as my session demonstrated. I found the official template, trusted it over the skill, and regressed. Templates are starter scaffolds that lag behind. The skill should warn against treating templates as authoritative for versions, not direct agents toward them.

Concrete recommendation

In the icp-cli skill, add:

1. A recipe reference table (type strings + config fields + latest versions)
2. One minimal canister.yaml example per recipe type
3. A one-liner: "Verify latest recipe versions at the releases page"
4. A note: "Do not infer recipe versions from template repositories — templates may lag behind"

This is ~40 lines of additions that would have prevented every issue in the session. Minimal maintenance cost (4 recipes, a few releases per year), maximum signal for agents writing config.