dfinity · raymondk · Aug 28, 2026 · Aug 28, 2026
@@ -56,7 +56,7 @@ Read with fresh eyes. Common high-value areas:
 
 **Required frontmatter** — `metadata.title` and `metadata.category` are required by CI. Missing these blocks deployment.
 
-For upstream-tracked skills (`motoko`, `migrating-motoko`, `migrating-motoko-enhanced`, `mops-cli`): read `.claude/upstream.md` carefully. Only modify icskills-owned sections freely; changes to shared content should also be filed upstream.
+For upstream-tracked skills (`writing-motoko`, `migrating-motoko-actors`, `troubleshooting-motoko-migrations`, `reviewing-motoko`, `mops-cli`, `static-site`): read `.claude/upstream.md` carefully. Only modify icskills-owned sections freely; changes to shared content should also be filed upstream.
 
 ## Step 4 — Apply improvements
 
@@ -176,4 +176,4 @@ The skill is ready for a PR. Include a brief summary of what changed and, if you
 
 ## Upstream-tracked skills
 
-Before editing `motoko`, `migrating-motoko`, `migrating-motoko-enhanced`, or `mops-cli`, read `.claude/upstream.md`. It lists which sections are icskills-owned. You can freely improve owned sections. For shared content, improvements should also be filed as issues upstream so they flow back on the next sync.
+Before editing `writing-motoko`, `migrating-motoko-actors`, `troubleshooting-motoko-migrations`, `reviewing-motoko`, `mops-cli`, or `static-site`, read `.claude/upstream.md`. It lists which sections are icskills-owned. You can freely improve owned sections. For shared content, improvements should also be filed as issues upstream so they flow back on the next sync.
@@ -117,7 +117,7 @@ All sync metadata lives in `.claude/upstream.md` — one entry per tracked skill
 Two tracking models are in use:
 
 - **Release-tracked** (`caffeinelabs/mops` → `mops-cli`; `dfinity/certified-assets` → `static-site`): pinned to a tagged release. When syncing, update the **Tag**, **Commit** (full SHA), and **Last synced** fields. Always store the **full commit SHA**, not just the tag name; annotated tags require a two-step dereference (tag object → commit SHA).
-- **Commit-tracked** (`caffeinelabs/skills` → `writing-motoko`, `migrating-motoko-actors`, `troubleshooting-motoko-migrations`): this upstream publishes **no releases**, so it is pinned to a commit on the default branch. When syncing, update the **Commit** (full SHA) and **Last synced** fields, and the **Upstream version** field (read from each skill's `version:` frontmatter — a secondary signal that meaningful changes landed). There is no **Tag**. All three skills from this repo share one pinned commit.
+- **Commit-tracked** (`caffeinelabs/skills` → `writing-motoko`, `migrating-motoko-actors`, `troubleshooting-motoko-migrations`, `reviewing-motoko`): this upstream publishes **no releases**, so it is pinned to a commit on the default branch. When syncing, update the **Commit** (full SHA) and **Last synced** fields, and the **Upstream version** field (read from each skill's `version:` frontmatter — a secondary signal that meaningful changes landed). There is no **Tag**. All four skills from this repo share one pinned commit.
 
 When the upstream SKILL.md references files that live within the upstream skill's folder (e.g. `examples.md`), list each with `→ references/<file>.md` to show the icskills path. icskills always places such files under `references/` regardless of how upstream organises them.
 
@@ -175,15 +175,15 @@ When new upstream content is available (a new release tag, or new commits on a c
 
 When syncing a skill from a new upstream release, verify all of these before committing:
 
-- [ ] **`.claude/upstream.md` updated** — Commit (full SHA) + Last synced for every skill entry that shares the upstream repo, plus Tag (release-tracked) or Upstream version (commit-tracked). E.g. syncing `caffeinelabs/skills` means updating all three of `writing-motoko`, `migrating-motoko-actors`, and `troubleshooting-motoko-migrations` — they share one pinned commit.
+- [ ] **`.claude/upstream.md` updated** — Commit (full SHA) + Last synced for every skill entry that shares the upstream repo, plus Tag (release-tracked) or Upstream version (commit-tracked). E.g. syncing `caffeinelabs/skills` means updating all four of `writing-motoko`, `migrating-motoko-actors`, `troubleshooting-motoko-migrations`, and `reviewing-motoko` — they share one pinned commit.
 - [ ] **All upstream skill folder files synced** — The sync issue diffs every file in the upstream skill folder (any type, not just `.md`) between old and new releases. Apply changes to all files that changed. If a file is new in upstream, add it to our `references/` directory. If a file was removed upstream, remove it from `references/` too. icskills always places reference files under `references/` regardless of how upstream organises them.
 - [ ] **Compatibility versions updated** — `compatibility:` frontmatter matches new feature requirements (e.g., `moc >= X.Y.Z, core >= A.B.C`)
 - [ ] **Version numbers in code examples** — All pinned versions in `mops.toml` snippets, `mops toolchain use` commands, and `mops add` examples reflect the new release
 - [ ] **All upstream additions applied** — Re-read every `+` line in the diff (lines new in upstream) systematically, including inside code blocks: added/changed inline comments, new sentences, modified expressions. These small changes are easy to miss but often carry clarifications or fixes.
 - [ ] **Icskills-owned sections preserved** — Sections listed as owned in `.claude/upstream.md` are NOT overwritten from upstream
 - [ ] **Owned sections audited against upstream additions** — For each owned section, check whether the upstream diff now covers the same content. If upstream ships it, drop the icskills copy and remove the entry from `.claude/upstream.md` to avoid duplicating agent instructions.
 - [ ] **Icskills-only content audited** — Any content we have that is absent from the upstream diff must be either listed as owned in `.claude/upstream.md` or removed. Content not tracked there is a gap — file an upstream issue or add it to the owned list.
-- [ ] **Cross-references use icskills skill names** — for `caffeinelabs/skills` the upstream and icskills names match (`writing-motoko`, `migrating-motoko-actors`, `troubleshooting-motoko-migrations`), so no rewrite is needed there. For other upstreams whose names differ, use the icskills name (e.g. `static-site`, not upstream's folder name)
+- [ ] **Cross-references use icskills skill names** — for `caffeinelabs/skills` the upstream and icskills names match (`writing-motoko`, `migrating-motoko-actors`, `troubleshooting-motoko-migrations`, `reviewing-motoko`), so no rewrite is needed there. For other upstreams whose names differ, use the icskills name (e.g. `static-site`, not upstream's folder name)
 - [ ] **Experimental/removed features excluded** — If upstream removed a command or feature (e.g., `mops migrate new/freeze`), remove it from the skill
 - [ ] **Evals reviewed** — Open `evaluations/<skill-name>.json` and apply the same logic as any improvement: (1) add new eval cases for new pitfalls, new commands, changed defaults, or renamed APIs in the diff — these are exactly where agents will hallucinate without updated guidance; (2) always run every case you added or changed with baseline (`node scripts/evaluate-skills.js <skill-name> --eval <N>`) and include those results in the PR — this verifies each new case passes with the skill and shows a real delta; (3) re-run untouched existing cases only if the diff modified content they cover. Collapse eval output in a `<details>` block.
 

@@ -60,6 +60,24 @@ Upstream file paths and the tracking model (release-tag vs commit) are listed pe
 
 ---
 
+## reviewing-motoko
+
+- **Upstream:** https://github.com/caffeinelabs/skills
+- **Tracking model:** commit-based (no releases/tags). Same as `writing-motoko`.
+- **Commit:** 90a2433578d0ea53fdbce3f51fb1dd3b8145ac04
+- **Upstream version:** 0.1.0 (skill frontmatter `version:`)
+- **Last synced:** 2026-08-28
+- **Pin note:** added at `90a2433` while the other three `caffeinelabs/skills` entries were still pinned at `9274f9b` (the skill did not exist there). Pins realign on the next full `caffeinelabs/skills` sync — until then, a sync issue may re-show this skill's content as newly added; verify against the local file instead of re-applying.
+- **Upstream files:**
+  - `skills/reviewing-motoko/SKILL.md`
+  - `skills/reviewing-motoko/references/state-and-persistence.md → references/state-and-persistence.md`
+  - `skills/reviewing-motoko/references/type-encoding.md → references/type-encoding.md`
+- **icskills-owned sections (do not overwrite from upstream):**
+  - **Frontmatter (entire block):** same transform as `writing-motoko` (owned `description` tuned for repo-wide trigger evals, `license: Apache-2.0`, string `compatibility` (`moc >= 1.11.2, core >= 2.6.0, mops >= 3.0.0`), `metadata.title`/`category`).
+  - **`## Additional resources` → `## Additional References`** (section renamed), plus an extra `- **mops tooling**: Load \`mops-cli\` …` bullet not in upstream.
+
+---
+
 ## static-site
 
 - **Upstream:** https://github.com/dfinity/certified-assets

@@ -0,0 +1,52 @@
+{
+  "skill": "reviewing-motoko",
+  "description": "Evaluations for the reviewing-motoko skill — design review of existing Motoko backends.",
+  "output_evals": [
+    {
+      "name": "text-status-and-correlated-fields",
+      "prompt": "Design-review this Motoko stable type and report findings with a severity level each, as in a code review. Just the findings — no full rewrite, no deploy steps:\n\n```motoko\npublic type Task = {\n  id : Nat;\n  var status : Text; // \"open\", \"claimed\", or \"done\"\n  hasDeadline : Bool;\n  deadline : ?Time.Time;\n};\n```",
+      "expected_behaviors": [
+        "Flags `status : Text` for a closed set of values as a defect and recommends a variant type (e.g. `{ #open; #claimed; #done }`) rather than runtime string comparison",
+        "Flags the correlated `hasDeadline : Bool` + `deadline : ?Time.Time` pair as encoding invalid states and recommends collapsing to a single field (the `?Time.Time` alone or a variant)",
+        "Notes that changing a type reachable from stable actor state requires a migration"
+      ]
+    },
+    {
+      "name": "mixin-var-by-value",
+      "prompt": "Under Motoko enhanced migration my actor declares `var nextId : Nat;` (value supplied by the migration chain) and passes it to a mixin with `include TasksApi(nextId)`. The mixin increments it, but the actor's field never changes. Review this and give the finding plus the fix, briefly.",
+      "expected_behaviors": [
+        "Identifies that `var` parameters are passed by value, so the mixin mutates a copy and the actor's field is never updated",
+        "Fix is to wrap the counter in a record (e.g. `let state : { var nextId : Nat }`) and pass that record binding to the mixin",
+        "Warns against constructing a fresh record literal at the include site (e.g. `include TasksApi({ var nextId = ... })`), which would again give the mixin its own copy"
+      ]
+    },
+    {
+      "name": "stable-inline-initializer",
+      "prompt": "Code review, brief — one finding with severity plus the exact fix, nothing else: my Motoko project uses the enhanced migration chain (`[canisters.backend.migrations]` in mops.toml). In main.mo the actor declares this top-level field holding durable user data that must survive upgrades:\n\n```motoko\nlet tasks = Map.empty<Nat, Types.Task>();\n```",
+      "expected_behaviors": [
+        "Flags the inline initializer on a stable field as invalid under enhanced migration — stable fields are declared type-only (compiler reports M0250 / M0014)",
+        "The proposed fix is to declare the field type-only (`let tasks : Map.Map<Nat, Types.Task>;`) and supply the initial value from the migration chain (the pending migration's NewActor)",
+        "The proposed fix keeps the field stable — it does not convert this durable user data to `transient`"
+      ]
+    }
+  ],
+  "trigger_evals": {
+    "description": "Queries to test whether the skill activates correctly. 'should_trigger' are review/audit/refactor tasks on existing Motoko code; 'should_not_trigger' are writing new code (writing-motoko), migration authoring (migrating-motoko-actors), tooling, or non-Motoko reviews.",
+    "should_trigger": [
+      "Review my Motoko backend for design issues",
+      "Can you audit this Motoko canister code and report findings by severity?",
+      "Refactor this existing Motoko actor — the types feel sloppy",
+      "Do a code review of my .mo files before I merge",
+      "Is holding the task status as Text good design in my Motoko type?",
+      "My Motoko project is one monolithic main.mo — review the structure"
+    ],
+    "should_not_trigger": [
+      "Write a Motoko canister with a counter",
+      "Fix this Motoko compilation error M0220",
+      "Write a migration to rename an actor field",
+      "How do I deploy my canister to mainnet?",
+      "Review my Rust canister for security issues",
+      "Run mops check on my project"
+    ]
+  }
+}
@@ -269,7 +269,8 @@
       "Generate TypeScript bindings for my canister",
       "What is the cycles cost of a canister?",
       "How do I pin the moc version in mops.toml?",
-      "Run mops check on my project"
+      "Run mops check on my project",
+      "Review my existing Motoko backend for design issues and report findings by severity"
     ]
   }
 }
@@ -36,11 +36,12 @@ fi
 # Local files live at skills/<local-name>/ in this repo.
 case "$REPO" in
   caffeinelabs/skills)
-    # No releases/tags; tracked by commit. The three Motoko skills share one pinned commit.
+    # No releases/tags; tracked by commit. The four Motoko skills share one pinned commit.
     SKILLS_BASE_PATH="skills"
     SKILLS="writing-motoko:writing-motoko
 migrating-motoko-actors:migrating-motoko-actors
-troubleshooting-motoko-migrations:troubleshooting-motoko-migrations"
+troubleshooting-motoko-migrations:troubleshooting-motoko-migrations
+reviewing-motoko:reviewing-motoko"
     ;;
   caffeinelabs/mops)
     SKILLS_BASE_PATH=".agents/skills"