playbooks

home / skills / shotaiuchi / dotclaude / migration-transform

migration-transform skill

/dotclaude/skills/migration-transform

This skill helps automate code migrations by transforming deprecated syntax, API updates, and import paths while preserving behavior.

npx playbooks add skill shotaiuchi/dotclaude --skill migration-transform

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.6 KB
---
name: migration-transform
description: >-
  Automated code transformation for migrations. Apply when performing codemods,
  syntax updates, API renames, import path changes, and pattern replacements
  across the codebase.
user-invocable: false
---

# Code Transformation

Perform automated code transformations for migration.

## Migration Checklist

### Syntax Transformations
- Identify deprecated syntax patterns requiring updates
- Apply language version syntax migrations consistently
- Verify transformed code preserves original semantics
- Check for edge cases missed by automated transforms

### API & Import Updates
- Rename changed API calls across the codebase
- Update import paths to reflect new module structure
- Replace removed APIs with recommended alternatives
- Verify no stale imports remain after transformation

### Pattern Replacements
- Convert deprecated patterns to idiomatic new patterns
- Replace obsolete utility usage with modern equivalents
- Update error handling to match new conventions
- Transform configuration formats to new schema

### Automated Verification
- Run transformed code through type checker and linter
- Verify all codemods are idempotent and safe to re-run
- Check that no unintended changes were introduced
- Validate transformation coverage with before/after diffs

## Output Format

Report findings with risk ratings:

| Risk | Description |
|------|-------------|
| Critical | Transformation alters program behavior, manual fix needed |
| High | Ambiguous transformation, requires human review |
| Medium | Transformation is safe but needs verification |
| Low | Straightforward rename or import update |

Overview

This skill performs automated code transformations for migration tasks across a codebase. It focuses on codemods, syntax updates, API renames, import path changes, and pattern replacements while producing a risk-rated report of findings. The goal is to make large-scale edits predictable, repeatable, and verifiable so teams can migrate with confidence.

How this skill works

The skill scans code for specified patterns and applies deterministic transforms such as AST-based syntax changes, API renames, and import path rewrites. It runs linters and type checkers after edits, generates before/after diffs, and classifies each change with a risk rating (Critical, High, Medium, Low). Outputs include a summary of changed files, suggested manual fixes, and verification steps for reviewers.

When to use it

  • Upgrading language versions that require syntax changes (e.g., new language constructs)
  • Renaming or deprecating public APIs and updating all callers
  • Refactoring module layout that requires import path updates
  • Replacing obsolete patterns or utilities with modern equivalents
  • Preparing a large codebase for a framework or library upgrade

Best practices

  • Design transforms to be idempotent so they can be safely re-run
  • Use AST-based edits rather than regex for semantic accuracy
  • Run type checks and linters as part of the verification step
  • Produce concise before/after diffs and attach example locations
  • Mark ambiguous changes as High or Critical for manual review

Example use cases

  • Automate renaming of an API method across hundreds of repositories and flag ambiguous callsites
  • Migrate import paths after a library reorganization and remove stale imports
  • Convert deprecated language constructs to the new syntax required by the latest compiler
  • Replace an obsolete utility module with its modern replacement and update usages
  • Transform configuration objects to a new schema and surface mismatches for manual correction

FAQ

How are risk ratings assigned?

Transforms are scored by potential behavioral impact: Critical alters behavior and needs manual fixes; High is ambiguous; Medium is likely safe but requires verification; Low is straightforward.

Can I preview changes before applying them?

Yes. The skill generates before/after diffs and a summary so you can review edits and run tests locally before committing.