Agent skill · caffeinelabs
reviewing-motoko
Design review for Motoko backends — invariants encoded in types, enhanced migration state discipline, and multi-file structure. Load when reviewing, auditing, or refactoring existing .mo files rather than writing new ones.
What it needs
About 10k tokens when loaded.
What this skill does
Reviewing Motoko This skill judges whether Motoko code is well designed. It does not teach the language — load writing-motoko for syntax, mo:core APIs, and mechanical rules, and migrating-motoko-actors before changing anything that is stable state. Four questions decide a review, in this order — the first three because each can invalidate the next, the fourth last because it is the least consequential: 1. Is every invariant the code relies on encoded in a type? Where the type system can rule out a bad state, leaving that to a runtime check or a comment is a defect, not a style preference. 2. Is state declared with the right persistence? Under enhanced migration, stable and transient are separate worlds. Blurring them produces state that silently stops updating. 3. Does the code live in the right files? types.mo / lib/ / mixins/ / main.mo is a contract about what may depend on what, not a folder convention. 4. Does it read like Motoko? Contextual dot notation, inferred implicits, no annotation the call already supplies, no classes. mops check --fix handles most of this; only what it cannot see is the reviewer's job. Procedure Run the mechanical pass first — do not spend review attention on what the compiler already reports. Its style auto-fixes (M0236 dot notation, M0237 redundant implicits, M0223 redundant instantiation) only fire where [moc] args enables -W for them; writing-motoko's references/project-setup.md has the setup. Where they are off, the Conventions findings below are all yours to make by hand. Then read in this order — outside in, because a misplaced file makes every type inside it suspect: 1. mops.toml — is there a [canisters..migrations] chain? If not, finding B1 below outranks everything else. 2. Structure — the file layout, then each file's imports. 3. types.mo — every type declaration. This is where most findings are. 4. State — the actor fields in main.mo, and what each include passes. See references/state-and-persistence.md. 5. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills caffeinelabs/reviewing-motoko