From aptos-agent-skills
Modernizes outdated Move V1 syntax, patterns, and APIs to V2+ including vector iterations, events, fungible assets, and signed integers. Use for upgrading legacy smart contracts.
npx claudepluginhub aptos-labs/aptos-agent-skills --plugin aptos-agent-skillsThis skill is limited to using the following tools:
Detect and modernize outdated Move V1 syntax, patterns, and APIs to Move V2+. Preserves correctness through tiered
Safely deploys Move contracts to Aptos devnet, testnet, or mainnet with pre-deployment checklist for security audits, tests, code quality, and config.
Upgrades Solidity contracts with OpenZeppelin UUPS, Transparent, or Beacon proxies. Covers Hardhat/Foundry workflows, initializers, storage safety (ERC-7201), validation, and v4-v5 restrictions.
Migrates legacy codebases to modern languages, frameworks, and patterns via automated refactoring, test generation, risk analysis, and dependency updates. Use for Python 2→3, JS→TS, React hooks, framework upgrades.
Share bugs, ideas, or general feedback.
Detect and modernize outdated Move V1 syntax, patterns, and APIs to Move V2+. Preserves correctness through tiered transformations with test verification after each tier.
Five non-negotiable rules for every modernization:
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.
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.
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.
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.
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.
public(friend) to package funvector::borrow to index notationwhile loops with counters to for range loopsvector::for_each_ref, vector::map, vector::fold,
etc.) and lambdascoin/TokenV1 to modern fungible_asset/Digital AssetsEventHandle to #[event] patterni8-i256 typeswrite-contractsanalyze-gas-optimizationsecurity-audit (run AFTER modernization)Entry: User provides a Move contract or project to modernize.
Actions:
.move files in sources/)Exit: Analysis Report ready for presentation.
Entry: Analysis Report complete.
Actions:
## 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)
syntax-only (Tier 1 only) — zero risk, just cleaner syntaxstandard (Tier 1 + Tier 2) — recommended default, syntax + visibility + error constantsfull (all tiers) — includes API migrations, higher riskExit: User has confirmed scope (and deployment context if Tier 3 is included). Do NOT proceed until confirmed.
Entry: User confirmed scope.
Actions:
#[test_only] modules within source files*_tests.move filestests/ directorygenerate-tests skill to create comprehensive tests first, then return hereaptos move test to establish a passing baselineExit: All tests pass. Baseline recorded. If tests fail pre-modernization, stop and address test failures first — do not modernize on a broken test suite.
Entry: Test baseline established.
Actions — apply in tier order:
Tier 1 (if scope includes it — always):
aptos move testTier 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)
compatible: skip any rule marked ⚠ Breaking. Add to the skipped list with reason
"breaking change, excluded in compatible mode."fresh deploy: apply all rules in scope normally.aptos move test after EACH individual Tier 3 changeExit: All approved changes applied, all tests passing.
Entry: All transformations applied.
Actions:
aptos move test --coverage## 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.
| 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 | 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 for the complete rule catalog (22 rules across 3 tiers).
| 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. |
full scope confirmation| File | Content |
|---|---|
| detection-rules.md | Complete V1 pattern detection catalog (22 rules across 3 tiers) |
| transformation-guide.md | Before/after code, safety checks, edge cases per rule |
| MOVE_V2_SYNTAX.md | Full V2 syntax reference |
| OBJECTS.md | Modern object model patterns |
| ADVANCED_TYPES.md | Enums, signed integers, phantom types |
Related skills: generate-tests, write-contracts, security-audit