skills

Error handling conventions for MoonBit projects. Use when designing error types, choosing between abort/fail/raise, writing catch blocks, defining FFI boundaries, or reviewing error handling patterns. Triggers on: error handling, abort, fail, raise, catch, Result, error types, fallible functions, boundary safety, error recovery.

Use when reviewing a MoonBit/Canopy change or pull request before merge and multiple independent review perspectives are useful

Use when writing or reviewing MoonBit code against the `dowdiness/incr` reactive library (v0.14.x+) — building Inputs/Deriveds/ReachableDeriveds, attaching long-lived derived cells with `Watch`/`Observer`, adding microbenchmarks, or wrapping a reactive pipeline in a struct. Catches recurring idiom misses (inside-vs-outside read semantics, GC-anchor `Watch`/`Observer`, `Type::Type` constructor naming, defensive copies).

Use when creating or editing a GitHub PR/issue body, comment, or commit message from a shell, or when writing a grep/rg search pattern — especially if the Markdown or pattern contains backticks, `$()`, `>`, or other shell metacharacters that could be expanded before the tool sees them.

Use when creating, removing, or working across git worktrees or submodules — before force-pushing, before deleting a worktree, after `git worktree add`, when merging or deleting branches with `gh pr merge`/`gh pr close`, when bumping a submodule pointer, when merging a stack of dependent PRs, or when another agent/process may be operating on the same checkout concurrently.

Use when writing MoonBit code involving derive(Debug) on container fields, a trait method whose name matches a callable field, JS-target-only public APIs or JS numeric formatting, `guard` early-exit syntax, package visibility (`pub` vs `pub(all)`) on mutable-container fields, or `moon fmt` touching a comment-only or multi-line closure body — silent-failure compiler/formatter behaviors that `moon check` and `moon fmt` don't flag.

Use when the user asks whether a PR is good/beneficial for the project, wants long-term (6–24 month) impact, architectural evaluation, technical-debt analysis, project-direction alignment, research/innovation value, a senior-maintainer/architect verdict, or follow-up issues derived from that analysis. NOT for ordinary bug-finding, security, or pre-merge correctness review (use code-review), and not for merging (use merge-pr).

End-of-session ritual: update memories for completed work, draft a self-contained next-session prompt, and report what's safe to drop from conversation context. Use when concluding a work session and preparing to /clear. Usage: /handoff [next-target-hint]

Use when writing or reviewing MoonBit code against the `dowdiness/loom` framework — constructing parsers with `new_parser`, updating `Parser` via `apply_edit`/`set_source`, attaching downstream `@incr.Derived` pipelines to `parser.runtime()`, or preserving semantic projection IDs with `ProjectionIdentityBaseline` / `ProjectionIdentityTracker`. Catches recurring mistakes such as constructing `@incremental.ImperativeParser` inside a reactive closure or advancing projection identity baselines before semantic lowering succeeds.

Guide for writing, refactoring, and testing MoonBit projects. Use when working in MoonBit modules or packages, organizing MoonBit files, using moon tooling (build/check/run/test/doc/ide etc.), or following MoonBit-specific layout, documentation, and testing conventions.

Set up MoonBit project instructions and agent configuration for coding assistants. Use when bootstrapping agent guidance, validation commands, hooks, project conventions, or shared MoonBit context for Codex, Claude Code, or other agent environments.

Guide for writing MoonBit bindings to C libraries using native FFI. Use when adding extern "c" declarations, writing C stubs with moonbit.h, configuring native-stub and link.native in moon.pkg, choosing

Tracks deprecated MoonBit syntax to avoid generating invalid code. Reference this before writing MoonBit code. Auto-maintained when deprecated patterns are discovered.

Guide to solving the Expression Problem in MoonBit using Finally Tagless encoding, two-layer architecture (tagless + concrete AST), polymorphic trait methods, and related patterns. Use when designing extensible data types, adding new variants or operations to existing code, working with Finally Tagless, Object Algebras, open recursion, or discussing extensibility trade-offs in MoonBit.

Implements opaque/newtype pattern in MoonBit for user-friendly public APIs. Use when designing type-safe wrappers, facade layers, or hiding implementation details in MoonBit libraries.

Use BEFORE any performance optimization in MoonBit. Requires reproducing the claimed bottleneck in an isolated microbenchmark before designing a solution. Triggers on "optimize", "performance", "bottleneck", "slow", "speed up", or any TODO item citing millisecond costs. Do NOT skip this for "obvious" optimizations.

Execution discipline for boundary-crossing MoonBit refactors: splitting packages with language-enforced isolation via `internal/`, extracting modules behind a `pub using` facade, splitting files safely, and pinning invariants with property tests before structural change. Use when the task is "split this package", "extract these files into an internal package", "verify the public API didn't change", or "set up tests before refactoring". Pairs with `moonbit-refactoring`, which covers *what* to refactor toward.

Refactor MoonBit code to be idiomatic: shrink public APIs, convert functions to methods, use pattern matching with views, add loop invariants, and ensure test coverage without regressions. Use when updating MoonBit packages or refactoring MoonBit APIs, modules, or tests.

Reference guide for effective trait usage in MoonBit's Self-based trait system (no trait type parameters, no associated types, but polymorphic trait methods are supported in v0.10+). Use when writing MoonBit traits, designing APIs with traits, or when the user asks about trait patterns like endomorphisms, capability traits, polymorphic methods, callback-based iteration, trait multiplication, newtypes, visitor pattern, or defunctionalized associated types in MoonBit.

Quality checklist for MoonBit development. Use when implementing or modifying MoonBit code to catch dependency issues, syntax mistakes, test failures, CLI bugs, and interface changes before they become problems.

Repo maintenance for MoonBit projects. Five subcommands: default (full audit-and-fix pipeline), check (fast read-only health check), fix (full check + auto-fix only), triage (project direction + branch pruning), release (pre-release prep). Use at session start, before commits, weekly for direction, and before releases.

Cross-repo and multiagent session setup workflow. Use when Codex needs to choose or verify the target repository, isolate work in a branch or worktree, decide whether to delegate to workers, supervise structured worker output, or coordinate coding work across multiple repos without mixing product contexts.

Single entry point for all MoonBit skills. Routes to the right specialist based on what you need: code quality, trait design, extensibility, performance, FFI, repo maintenance, etc. Use /moonbit <what you need> instead of remembering individual skill names.

Guidance for tuple struct wrapper APIs that use public named constructors and internal tuple constructors; use when designing newtypes/wrappers, deciding constructor visibility, or documenting public vs internal usage.