Modernize Move

Skill: modernize-move

Detect and modernize outdated Move V1 syntax, patterns, and APIs to Move V2+. Preserves correctness through tiered transformations with test verification after each tier.

Essential Principles

Five non-negotiable rules for every modernization:

1. Test safety net is mandatory WHY: Modernization must preserve behavior. No tests = no safety net. If no tests

exist, invoke generate-tests skill first to create comprehensive tests before making any changes.

1. Analyze before modifying WHY: The user must see exactly what will change and confirm the scope. Never

surprise-edit code. Present the full analysis report and wait for confirmation.

1. Tiered execution order WHY: Syntax changes (Tier 1) are zero-risk. API migrations (Tier 3) change semantics.

Always apply safest changes first so riskier changes build on a clean, verified foundation.

1. Verify after each tier WHY: If tests break, you know exactly which tier caused it. Revert that tier and

investigate before proceeding. Never apply the next tier on a broken baseline.

1. Preserve error code values WHY: Tests use #[expected_failure(abort_code = N)]. Changing numeric values breaks

tests silently. When creating named constants, the numeric value MUST match the original literal.

When to Use This Skill

• Upgrading Move V1 contracts to V2 syntax
• Migrating public(friend) to package fun
• Converting vector::borrow to index notation
• Converting while loops with counters to for range loops
• Replacing manual vector iteration with stdlib inline functions (vector::for_each_ref, vector::map, vector::fold,

etc.) and lambdas

• Replacing magic abort numbers with named constants
• Migrating legacy coin/TokenV1 to modern fungible_asset/Digital Assets
• Converting EventHandle to #[event] pattern
• Upgrading custom signed integer workarounds to native i8-i256 types

When NOT to Use This Skill

• Writing new contracts from scratch — use write-contracts
• Fixing bugs or adding features — modernization is structural, not functional
• Optimizing gas usage — use analyze-gas-optimization
• Auditing security — use security-audit (run AFTER modernization)

Workflow

Phase 1: Analyze Contract

Entry: User provides a Move contract or project to modernize.

Actions:

1. Read all contract source files (.move files in sources/)
2. Scan for V1 patterns using detection rules from [detection-rules.md](references/detection-rules.md):

• Grep for Tier 1 patterns (syntax) — highest confidence, most common
• Grep for Tier 2 patterns (visibility, errors, events)
• Grep for Tier 3 patterns (API migrations) — flag for manual review

1. Cross-reference coupled patterns (T3-09+T3-10)
2. Categorize each finding: line number, rule ID, pattern name, proposed change, tier, confidence
3. Build the Analysis Report

Exit: Analysis Report ready for presentation.

Phase 2: Present Analysis (GATE 1)

Entry: Analysis Report complete.

Actions:

1. Present the full Analysis Report to the user in this format:

## Modernization Analysis Report

### Summary
- Tier 1 (Syntax): X findings
- Tier 2 (Visibility & Errors): X findings
- Tier 3 (API Migrations): X findings

### Findings

| # | File:Line | Rule | Pattern | Proposed Change | Tier | Confidence |
|---|-----------|------|---------|-----------------|------|------------|
| 1 | src/mod.move:15 | T1-01 | vector::borrow | → index notation | 1 | High |
| ... | ... | ... | ... | ... | ... | ... |

### Tier 3 Warnings (if any)
- T3-03: coin → fungible_asset migration is a major rewrite (X locations)

1. Ask the user to choose scope:

• syntax-only (Tier 1 only) — zero risk, just cleaner syntax
• standard (Tier 1 + Tier 2) — recommended default, syntax + visibility + error constants
• full (all tiers) — includes API migrations, higher risk

1. Highlight any Tier 3 items that require major rewrites
2. If scope includes Tier 3, ask the user about deployment context:

• Compatible — Upgrading an already-deployed contract. Breaking changes are excluded even if the scope includes

them. Rules marked ⚠ Breaking are skipped.

• Fresh deploy — New deployment or willing to redeploy. All changes in the selected scope are applied including

breaking changes.

Exit: User has confirmed scope (and deployment context if Tier 3 is included). Do NOT proceed until confirmed.

Phase 3: Establish Test Safety Net

Entry: User confirmed scope.

Actions:

1. Search for existing tests:

• #[test_only] modules within source files
• *_tests.move files
• tests/ directory

1. If no tests found: stop and invoke generate-tests skill to create comprehensive tests first, then return here
2. Run aptos move test to establish a passing baseline
3. Record baseline: number of tests, all passing status

Exit: All tests pass. Baseline recorded. If tests fail pre-modernization, stop and address test failures first — do not modernize on a broken test suite.

Phase 4: Apply Transformations (with Feedback Loops)

Entry: Test baseline established.

Actions — apply in tier order:

Tier 1 (if scope includes it — always):

1. Apply all Tier 1 syntax changes per [transformation-guide.md](references/transformation-guide.md)
2. Run aptos move test
3. If tests fail → revert all Tier 1 changes, investigate which specific change caused failure, fix and retry

Tier 2 (if scope is standard or full): 4. Apply all Tier 2 changes per transformation guide 5. Run aptos move test 6. If tests fail → revert all Tier 2 changes, investigate and fix

Tier 3 (if scope is full only): 7. Apply Tier 3 changes ONE AT A TIME (not all at once)

• If deployment context is compatible: skip any rule marked ⚠ Breaking. Add to the skipped list with reason

"breaking change, excluded in compatible mode."

• If deployment context is fresh deploy: apply all rules in scope normally.

1. Run aptos move test after EACH individual Tier 3 change
2. If tests fail → revert that specific change, note it as skipped, proceed to next Tier 3 item

Exit: All approved changes applied, all tests passing.

Phase 5: Final Verification

Entry: All transformations applied.

Actions:

1. Run aptos move test --coverage
2. Verify test coverage is >= baseline (should be same or better)
3. Generate Modernization Summary Report:

## Modernization Summary

### Changes Applied
- Tier 1: X changes (syntax)
- Tier 2: X changes (visibility & errors)
- Tier 3: X changes (API migrations)

### Changes Skipped
- [List any skipped items with reasons]

### Test Results
- Tests: X passing (baseline: Y)
- Coverage: X% (baseline: Y%)

### Files Modified
- [List of modified files]

Exit: Report presented to user.

Modernization Scope Quick Reference

| Scope | Tiers | Risk | When to Use | | ------------- | ---------- | ----------- | -------------------------------------------------- | | syntax-only | Tier 1 | Zero | Just clean up syntax, no semantic changes | | standard | Tier 1+2 | Low | Default. Syntax + visibility + error constants | | full | Tier 1+2+3 | Medium-High | Full migration including API changes |

Tier Quick Reference

| Tier | What Changes | Risk | Examples | | ----------------------- | ---------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 — Syntax | Code reads differently, compiles identically | Zero | vector::borrow(&v, i) → v[i], x = x + 1 → x += 1, while (i < n) { ... i += 1 } → for (i in 0..n) { ... } | | 2 — Visibility & Errors | Same semantics, cleaner declarations | Low | public(friend) → package fun, magic numbers → E_* constants | | 3 — API Migrations | Different APIs, same intended behavior. Most are breaking changes. | Medium-High | coin → fungible_asset, SmartTable → BigOrderedMap, EventHandle → #[event], manual loops → stdlib v.for_each_ref()/v.map()/v.fold() with lambdas |

See [detection-rules.md](references/detection-rules.md) for the complete rule catalog (22 rules across 3 tiers).

Rationalizations to Reject

| Rationalization | Why It's Wrong | | ------------------------------------------------ | ------------------------------------------------------------------------------ | | "Tests pass so the modernization is correct" | Tests verify behavior, not code quality. Review changes manually too. | | "This contract is simple, skip the analysis" | Simple contracts can have subtle patterns. Always analyze first. | | "Let's do all tiers at once to save time" | If tests break, you can't isolate which change caused it. Always tier. | | "The receiver-style call looks right" | Must verify the target function declares self. False positives are common. | | "Error constants can have new names and values" | Existing tests depend on exact numeric values. Preserve them. | | "No tests exist, but the changes are safe" | Without tests there is no safety net. Generate tests first. | | "Tier 3 changes are optional, skip the test run" | Every change needs verification. Tier 3 is highest risk — test MORE, not less. |

Success Criteria

• [ ] Analysis Report presented before any modifications
• [ ] User confirmed modernization scope
• [ ] Test baseline established before changes
• [ ] Tests pass after each tier of changes
• [ ] All error code numeric values preserved
• [ ] No Tier 3 changes applied without full scope confirmation
• [ ] Breaking changes excluded when user selected compatible mode
• [ ] Modernization Summary Report generated
• [ ] Test coverage maintained at or above baseline

Reference Index

| File | Content | | ------------------------------------------------------------- | --------------------------------------------------------------- | | [detection-rules.md](references/detection-rules.md) | Complete V1 pattern detection catalog (22 rules across 3 tiers) | | [transformation-guide.md](references/transformation-guide.md) | Before/after code, safety checks, edge cases per rule | | [MOVEV2SYNTAX.md](../../../patterns/move/MOVEV2SYNTAX.md) | Full V2 syntax reference | | [OBJECTS.md](../../../patterns/move/OBJECTS.md) | Modern object model patterns | | [ADVANCEDTYPES.md](../../../patterns/move/ADVANCEDTYPES.md) | Enums, signed integers, phantom types |

Related skills: generate-tests, write-contracts, security-audit

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aptos-labs
• Source: aptos-labs/aptos-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.