mizchi/moonbit-practice

Overview

This skill packages MoonBit code-generation best practices to guide AI and developers when writing MoonBit code. It focuses on avoiding common syntax mistakes, using semantic tooling, and keeping tests and benchmarks correct. Use it to produce code that compiles, follows language conventions, and integrates with MoonBit tooling.

How this skill works

The skill inspects generated MoonBit code and suggests fixes for common AI errors (type parameter placement, raise syntax, macro calls, async/error usage, loop styles). It recommends using moon ide and moon doc for semantic navigation rather than file grep or raw reads, and enforces test/benchmark snapshot conventions and doc-test formats. It also provides a pre-release checklist and guidance for CI and tooling commands.

When to use it

• When generating or reviewing MoonBit source to avoid compilation errors from common AI patterns.
• Before committing changes to ensure tests, snapshots, and generated type files are correct.
• When converting examples into runnable doc-tests or snapshot tests.
• During refactors that touch error propagation, async functions, or type parameters.
• When adding or updating CI, test, or benchmark configuration for a MoonBit repo.

Best practices

• Prefer moon ide commands (peek-def, find-references, outline, hover) over Read/grep for semantic code navigation.
• Use moon doc '<Type>' to explore APIs before implementing or guessing signatures.
• Follow MoonBit syntax: fn[T] name(...), use 'raise' for checked errors, avoid 'return' and C-style ++/--.
• Write doc-tests in .mbt.md or ///| blocks with proper ```mbt test/check/moonbit annotations.
• Run moon fmt and moon info before release; do not edit pkg.generated.mbti manually.
• Use functional for-loops and range-based loops; prefer nobreak for loop exit values.

Example use cases

• AI generates a parser: use moon ide peek-def and moon doc to confirm APIs and fix raise syntax.
• Converting prose examples into doc-tests: format blocks as ```mbt test in ///| comment sections.
• Updating snapshots: run moon test -u so inspect(content) entries are auto-populated.
• Refactoring error handling: replace deprecated -> T!Error syntax with -> T raise Error and use try?/catch patterns.
• Preparing release CI: run moon fmt and moon info, ensure pkg.generated.mbti is produced by moon info.