# Move Code Review โ Claude Code Skill
A Claude Code skill that performs security, architecture, and design review on Sui Move smart contracts. Based on patterns from 40+ production Move contract reviews.
## What It Checks
| Category | ID Prefix | Checks | Focus |
|----------|-----------|--------|-------|
| **Security** | `SEC-` | 8 | Access control, arithmetic safety, logic errors |
| **Design** | `DES-` | 10 | Object model, data structures, function composability, blind transfers |
| **Patterns** | `PAT-` | 4 | Capability patterns, version management |
| **Testing** | `TST-` | 5 | Coverage gaps, validation, bounds checking |
| **Quality** | `QA-` | 8 | Unused code, module organization, naming, documentation |
| **Config** | `CFG-` | 4 | Hardcoded values, magic numbers, metadata |
**Total: 40 checks** across 6 categories with pre-assigned severity weights.
## Severity Levels
| Level | Weight | Meaning |
|-------|--------|---------|
| S1 Critical | 10 | Financial loss, unauthorized access, data corruption |
| S2 High | 7 | Incorrect behavior, DoS, data integrity loss |
| S3 Medium | 4 | Maintainability, scalability, composability risk |
| S4 Low | 2 | Code quality, documentation, style |
## Complementarity with move-code-quality
This skill and `/move-code-quality` cover different domains:
| | move-code-review (this) | move-code-quality |
|---|---|---|
| **Focus** | Security, architecture, design | Syntax, idioms, Move 2024 compliance |
| **Source** | 40+ production reviews | Move Book Code Quality Checklist |
| **Checks** | Access control, arithmetic, object model | Module labels, imports, macros, method syntax |
**Run both for a complete review.**
## Installation
```bash
git clone https://github.com/alilloig/move-code-review-skill ~/.claude/skills/move-code-review
```
Or as a git submodule in your claudefiles:
```bash
cd ~/workspace/claudefiles
git submodule add https://github.com/alilloig/move-code-review-skill skills/move-code-review
```
## Usage
```
/move-code-review
```
The skill produces a structured report with:
- Findings summary table (ID, severity, weight, category, file, summary)
- Detailed findings with code snippets and fixes
- Risk score with severity breakdown
- Strengths and recommended next steps
## Evaluating the Skill
The repo includes two evaluation tools:
- **`run-eval.sh`** โ Compare skill vs no-skill baseline on a single package
- **`compare-skills.sh`** โ Compare two skill variants (e.g. main vs a branch) across multiple packages
### Prerequisites
- Python 3.10+
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude` command)
### Run evals (skill vs baseline)
```bash
./scripts/run-eval.sh /path/to/your/move/package
```
This runs 3 eval scenarios (full review, scoped review, risk score), each with and without the skill, then opens a browser-based viewer to compare the results.
To compare against a previous run:
```bash
./scripts/run-eval.sh /path/to/package --previous evals/runs/20260323-143000-my_package
```
### Compare skill variants
Compare the main branch skill against a candidate variant (e.g. a worktree, branch checkout, or any directory with a SKILL.md):
```bash
./scripts/compare-skills.sh <candidate-root> <package-path> [<package-path>...] [options]
```
**Arguments:**
- `<candidate-root>` โ Path to the candidate skill root (must contain `SKILL.md`). Can be relative to the project root (e.g. `worktrees/my-branch`).
- `<package-path>` โ One or more paths to Move packages to evaluate.
**Options:**
| Flag | Description |
|------|-------------|
| `--parallel` | Run both variants concurrently for each eval |
| `--runs N` | Runs per (eval, variant) for statistical confidence (default: 1). Use 3+ to get meaningful stddev. |
| `--evals LIST` | Comma-separated eval names (default: all three) |
| `--label NAME` | Label for the candidate config (default: derived from path) |
| `--no-grade` | Skip auto-grading (produces side-by-side reviews + timing only) |
| `--no-report` | Skip HTML report generation |
**Examples:**
```bash
# Full comparison: main vs worktree on multiple packages
./scripts/compare-skills.sh worktrees/code-snipets \
~/workspace/my-project/packages/auth \
~/workspace/my-project/packages/core \
--parallel
# Quick check: risk-score only on a single package
./scripts/compare-skills.sh worktrees/my-experiment \
~/workspace/some-project/packages/token \
--evals risk-score
# Custom label for the candidate
./scripts/compare-skills.sh /tmp/skill-v2 \
~/workspace/project/packages/main \
--label v2_with_examples --parallel
```
**What it does:**
1. Runs each eval prompt with both skill variants against each package
2. Auto-grades each review output against structural expectations (10 for full-review, 6 for scoped, 5 for risk-score)
3. Extracts content-level metrics from each review (word count, findings count, severity distribution, line references, code snippets, structure completeness)
4. Aggregates grading + content metrics into a benchmark with pass rates, timing, and deltas
5. Generates a self-contained static HTML report
**Output:**
```
evals/comparisons/<timestamp>-<package>/
โโโ comparison-report.html # Self-contained, sharable
โโโ benchmark.json # Structured metrics (grading + content)
โโโ benchmark.md # Markdown summary table
โโโ eval-{1..N}/ # Per-eval results
โโโ main_skill/
โ โโโ eval_metadata.json
โ โโโ run-1/
โ โโโ outputs/review.md
โ โโโ timing.json
โ โโโ status.json # Run success/failure + exit code
โ โโโ stderr.log # Captured stderr from claude invocation
โ โโโ grading.json
โโโ <candidate_label>/
โโโ ...
```
**Setting up a worktree for comparison:**
```bash
# Create a worktree from a branch
git worktree add worktrees/my-branch my-branch
# Or create one for a new experimental branch
git worktree add -b experiment worktrees/experiment
# Edit SKILL.md and references/ in the worktree, then compare
./scripts/compare-skills.sh worktrees/experiment /path/to/package --parallel
```
### View existing results
View any previous eval run directly:
```bash
python3 eval-viewer/generate_review.py evals/runs/<run-dir> --skill-name move-code-review
```
Or generate a static HTML file:
```bash
python3 eval-viewer/generate_review.py evals/runs/<run-dir> --static report.html
```
### Eval output structure (run-eval.sh)
```
evals/runs/<timestamp>-<package>/
โโโ full-review/
โ โโโ eval_metadata.json
โ โโโ with_skill/
โ โ โโโ outputs/review.md
โ โ โโโ timing.json
โ โโโ without_skill/
โ โโโ outputs/review.md
โ โโโ timing.json
โโโ scoped-review/
โ โโโ ...
โโโ risk-score/
โโโ ...
```
## Metrics
The output format is designed for automated extraction. Each finding has a unique ID and fixed weight, enabling:
- Per-package risk scores
- Cross-review trend analysis
- Category-level vulnerability tracking
- Severity distribution dashboards
### Benchmark content metrics
When comparing skill variants, `aggregate_benchmark.py` extracts these additional metrics from each review output:
| Metric | Description |
|--------|-------------|
| `word_count` | Total words in the review |
| `findings_count` | Number of findings in the findings table |
| `severity_distribution` | Count of S1/S2/S3/S4 findings |
| `line_references` | Count of `.move:N` line number references |
| `code_snippets` | Count of ` ```move ` code blocks |
| `structure_completeness` | Fraction of expected sections present (0.0โ1.0) |
These appear in `benchmark.json` per-run and as aggregated statistics (mean, stddev, min, max) in the summary.
## License
MIT