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 and moon --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 '' 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 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

Reference routing

Load only what the task needs:

• Module/package layout, moon.mod & moon.pkg DSL, legacy JSON mapping → references/project-layout-and-config.md
• Everyday commands (new, check, build, run, test, fmt, info, doc, clean) with verified flags → references/commands.md
• Test filtering, snapshot updates, doc tests, coverage, benchmarks → references/testing-workflows.md
• Dependencies, mooncakes registry, publishing, packaging → references/dependencies-and-registry.md
• Target selection, preferred/supported targets, per-file conditional builds, link options, native stubs → references/targets-and-conditional-builds.md
• Semantic code queries (peek-def, outline, doc search, hover, references, rename) → references/moon-ide.md
• moon.work workspaces, .mbtx script mode, pre-build rules → references/workspaces-and-scripts.md
• Diagnosing build/test/dependency failures, moon explain, warning lists → 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 → report upstream (with consent): 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hyfdev
• Source: hyfdev/moonbit-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.