Moonbit toolchain

MoonBit toolchain

Verification contract

Every command and configuration shape in this skill was executed for real against moon 0.1.20260713 / moonrun 0.1.20260713 (MoonBit release 0.10.4, build 2026-07-13) on 2026-07-18, Linux x86_64, exercising targets wasm-gc, wasm, js, native. MoonBit ships install channels (latest, nightly, pre-release), not pinned historical versions, so local installs drift forward automatically.

Before relying on this skill, run moon version --all (or node scripts/env_report.ts, which also checks native-backend prerequisites). If versions differ from the pin:

1. Prefer moon help <subcommand> and moon <subcommand> --help output over this skill for exact flags.
2. Re-run any load-bearing command in a scratch module (moon new probe --user tmp) before promising its behavior.
3. Check https://www.moonbitlang.com/updates/ for toolchain changes since 0.10.4.
4. State the version difference in your answer.

Non-negotiable working rules

• Run commands, don't recall them. Flags and defaults changed repeatedly (build dir is _build now, not target; moon ide exists; moon explain exists). If you cannot execute, quote --help output or mark the answer unverified.

• Config formats are mid-migration. The current formats are the non-JSON moon.mod / moon.pkg DSL; moon.mod.json / moon.pkg.json are deprecated in v0.10.4 and scheduled for removal. Both still parse at the pin. Never create new JSON configs; never mix advice between the two formats without labeling which is which. See references/project-layout-and-config.md.

• Don't guess package or API availability. Use moon ide doc '<query>' for installed APIs and the mooncakes registry for packages; a familiar name from npm/crates is not evidence a MoonBit package exists.

• Prefer the narrowest verifying command and show it: moon check after config edits, targeted moon test <path> for test questions, moon info to prove API-surface claims.

• Never run destructive or account-level commands unprompted: moon publish, moon register, moon login, moon upgrade change global or remote state — describe them instead, and only run them on explicit request.

• If a command or config contradicts this skill, complete the reporting protocol before the final response rather than merely mentioning the mismatch. Rebuild it in a scratch module with generic names, prepare a privacy-scrubbed public issue draft, show the user its exact title and body, and provide the issue-template link. Stop there: never submit the issue or invoke GitHub from this skill workflow, even if the user gave blanket or draft-specific permission. A later request for the host agent to send it is a separate outbound action governed by that client's own approval controls. Never edit the installed skill copy or write the draft into the user's repository. Exact protocol: references/reporting-errors.md

Feature index

Load only what the task needs:

• Module/package layout and Internal Packages; moon.mod / moon.pkg; deprecated moon.mod.json / moon.pkg.json; source; formatter; pkgtype; #export_name; virtual packages with options("virtual"), implement, and overrides → references/project-layout-and-config.md
• Everyday moon new, check, build, run, test, fmt, info, doc, and clean; executed-program exit code → references/commands.md
• Test path filtering, snapshots, doc tests, coverage, moon bench PATH, and raw benchmark statistics → references/testing-workflows.md
• Dependencies, mooncakes registry, publishing, and packaging → references/dependencies-and-registry.md
• Target selection; preferred-target; supported targets; native platform matrix; conditional builds; link options; native stubs → references/targets-and-conditional-builds.md
• Semantic code queries including peek-def, outline, doc search, hover, references, and rename → references/moon-ide.md
• moon.work workspaces, .mbtx script mode, module-root test and pre-build execution, and pre-build paths → references/workspaces-and-scripts.md
• Build, test, and dependency diagnostics; moon explain; warning lists and --deny-warn → references/diagnostics-and-recovery.md

Every moon ... command line shown in these references is executed against the pinned toolchain by the source repository's CI — the examples are guaranteed to have run, not just to look plausible.

• Toolchain contradicts this skill; minimal reproduction and issue draft → references/reporting-errors.md

Boundary

This skill owns project operation: configuration files, commands, dependencies, targets, publishing, CI. What MoonBit code means — types, pattern matching, traits, error semantics, FFI declaration syntax — is the moonbit-language skill. For tasks that span both (a new package including its code, FFI declarations plus link configuration, repos broken in both code and config), load both skills.