moonbit-agent-guide

This skill acts as a comprehensive technical companion for developers building projects in MoonBit. It provides structured guidance on navigating the MoonBit ecosystem, from initializing new modules to maintaining robust, production-ready codebases. Whether you are setting up your project directory, managing cross-package dependencies, or optimizing for MoonBit's specific concurrency and safety patterns, this agent assists with configuration, refactoring, and debugging tasks.

The agent is designed for software engineers working on MoonBit projects who need to follow idiomatic project layouts, ensure type safety, and leverage the moon CLI efficiently. It excels at explaining how to transition from individual .mbt files to cohesive packages, how to write white-box and black-box tests, and how to interpret compiler-generated .mbti interface files. It also helps developers avoid common pitfalls such as incorrect mutable record field handling, improper error propagation, or misuse of reserved syntax.

• Project Scaffolding: Create and manage moon.mod.json and moon.pkg.json configurations for complex, multi-package repositories.

• Tooling Automation: Execute and troubleshoot core workflows including moon build, moon check, moon test, and moon doc.

• Refactoring Support: Safely split, merge, or reorganize declarations across .mbt files without breaking package semantics.

• Idiomatic Coding: Guidance on using the mut keyword, handling array bounds with get(), and adopting current syntax over legacy ! or ? patterns.

• Testing Frameworks: Setup for *_test.mbt black-box tests and integrated README.mbt.md documentation-test cycles.

• Always ensure you define packages in directories containing moon.pkg.json, as moon commands must be run from the root module directory.

• Prioritize the use of .mbti interface files to verify public API surfaces during code reviews.

• Avoid hard-coding path assumptions; rely on the module system to reference code via @username/module_name/package_path.

• When encountering compilation errors, verify that functions are properly prefixed with the Type:: nomenclature and that variables use camelCase/snake_case as per MoonBit requirements.