Skip to main content
skill CX Codex

magento-upgrade-specialist — Claude Code skill

magento-upgrade-specialist — a skill for Magento 2 upgrades, Magento 1 migrations, compatibility checks, and breaking-change planning across custom code and extensions.

MIT 176 installs ★ 33 updated 2026-01-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add maxnorm/magento2-agent-skills --skill magento-upgrade-specialist -a claude-code
Open on GitHub

What magento-upgrade-specialist does

This skill audits a Magento installation before an upgrade. It reviews custom modules, themes, modifications, third-party extensions, database consistency, and the current performance baseline. Static analysis, API review, deprecated-feature checks, and schema inspection help surface compatibility work.

It then helps choose a direct or incremental route, prepare development, staging, and production environments, plan data migration, and define recovery steps. The workflow covers custom code, Composer dependencies, configuration, database changes, extensions, and frontend updates. Magento 1.x to Magento 2.x migrations also include data transformation, theme work, extension replacement, and custom-code rewrites.

The skill includes commands for checking the Magento version and database status, creating a mysqldump backup, changing Composer dependencies, and running bin/magento setup:upgrade, compilation, static-content deployment, cache flushing, and reindexing. A move from 2.3.x to 2.4.x requires a PHP compatibility check, since that upgrade category includes PHP version requirements.

What it helps with

  • plan a Magento 2 version upgrade
  • check custom code and extension compatibility
  • prepare a Magento 1.x to Magento 2.x migration
  • identify breaking API and database changes
  • define upgrade testing and rollback steps

Example prompts for the agent

  • Audit this Magento installation and create a plan for the target version upgrade.
  • Check the extensions and Composer dependencies for compatibility before the upgrade.
  • Map a Magento 1.x to Magento 2.x migration and include recovery steps.

How to install magento-upgrade-specialist

1Skills CLI (Vercel)

npx skills add maxnorm/magento2-agent-skills --skill magento-upgrade-specialist -a claude-code

2Manually: put the files in place

~/.claude/skills/magento-upgrade-specialist/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/magento-upgrade-specialist/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about magento-upgrade-specialist

How do I install magento-upgrade-specialist in Claude Code?

Run npx skills add maxnorm/magento2-agent-skills --skill magento-upgrade-specialist -a claude-code, then check ~/.claude/skills/magento-upgrade-specialist/SKILL.md.

What does magento-upgrade-specialist do?

It audits Magento before an upgrade, reviews code and extension compatibility, and structures migration, implementation, testing, and rollback work.

What should I check when moving from Magento 2.3.x to 2.4.x?

Review PHP compatibility, Composer dependencies, and core API changes. Database schema, configuration, and third-party extensions also need review.

Source text

SKILL.md · MIT
---
name: magento-upgrade-specialist
description: Manages seamless Magento 2 version upgrades and migrations. Use when upgrading Magento versions, migrating from Magento 1, planning upgrade strategies, assessing compatibility, or handling breaking changes. Masters upgrade planning, compatibility assessment, and post-upgrade optimization.
---

# Magento 2 Upgrade Specialist

Expert specialist in ensuring smooth, risk-free transitions between Magento versions while maintaining business continuity and preserving custom functionality.

## When to Use

- Upgrading Magento 2 versions (minor or major)
- Migrating from Magento 1.x to Magento 2.x
- Planning upgrade strategies and timelines
- Assessing extension compatibility
- Handling breaking changes
- Post-upgrade optimization

## Upgrade Process Framework

### 1. Pre-Upgrade Assessment
- **Current System Audit**: Comprehensive analysis of existing Magento installation
- **Custom Code Review**: Evaluate all custom modules, themes, and modifications
- **Extension Compatibility**: Check third-party extension compatibility with target version
- **Data Integrity Check**: Verify database consistency and identify potential issues
- **Performance Baseline**: Establish current performance metrics for comparison

### 2. Compatibility Analysis
- **Static Code Analysis**: Use automated tools to identify compatibility issues
- **API Change Review**: Analyze breaking changes in core APIs and interfaces
- **Deprecated Feature Assessment**: Identify and plan replacement for deprecated functionality
- **Database Schema Changes**: Review required database modifications
- **Configuration Changes**: Identify system configuration updates needed

### 3. Migration Planning
- **Upgrade Path Strategy**: Choose optimal upgrade path (direct vs. incremental)
- **Environment Setup**: Plan development, staging, and production upgrade environments
- **Downtime Minimization**: Develop strategies to reduce production downtime
- **Data Migration Strategy**: Plan for large dataset migrations and optimizations
- **Contingency Planning**: Prepare for various failure scenarios and recovery procedures

### 4. Implementation Execution
- **Code Migration**: Update custom code to work with target Magento version
- **Database Upgrade**: Execute database schema and data migrations
- **Configuration Migration**: Transfer and update system configurations
- **Extension Updates**: Upgrade or replace third-party extensions
- **Testing Validation**: Comprehensive testing of all upgraded functionality

## Upgrade Categories

### Minor Version Upgrades (2.4.x to 2.4.y)
- **Security Patches**: Apply critical security updates
- **Bug Fixes**: Resolve known issues and stability improvements
- **Feature Enhancements**: Leverage minor feature additions
- **Compatibility Updates**: Maintain extension and custom code compatibility
- **Performance Improvements**: Benefit from performance optimizations

### Major Version Upgrades (2.3.x to 2.4.x)
- **PHP Version Updates**: Handle PHP version compatibility requirements
- **Composer Dependencies**: Update package dependencies and constraints
- **API Changes**: Adapt to breaking changes in core APIs
- **New Architecture**: Leverage new architectural improvements
- **Migration Tools**: Utilize official migration utilities and scripts

### Legacy Migrations (Magento 1.x to 2.x)
- **Data Migration**: Comprehensive data structure transformation
- **Theme Migration**: Complete frontend redesign and implementation
- **Extension Replacement**: Find and implement Magento 2 equivalents
- **Custom Code Rewrite**: Rebuild custom functionality for Magento 2
- **Training Requirements**: Team training on Magento 2 architecture

## Upgrade Commands

### Pre-Upgrade
```bash
# Check current version
bin/magento --version

# Check database status
bin/magento setup:db:status

# Backup database
mysqldump -u user -p database > backup.sql

# Check extension compatibility
composer show | grep magento
```

### During Upgrade
```bash
# Update composer dependencies
composer require magento/product-community-edition:2.4.x --no-update
composer update

# Run upgrade
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush
bin/magento indexer:reindex
```

### Post-Upgrade
```bash
# Verify installation
bin/magento setup:db:status
bin/magento setup:upgrade

# Test functionality
# Run automated tests
# Manual testing checklist
```

## Common Upgrade Challenges

### Breaking Changes
- **API Changes**: Update code using deprecated APIs
- **Class Changes**: Update class references and namespaces
- **Configuration Changes**: Update XML configuration files
- **Database Schema**: Handle schema changes and migrations
- **Frontend Changes**: Update templates and layouts

### Extension Compatibility
- **Version Conflicts**: Resolve composer dependency conflicts
- **API Compatibility**: Update extensions using deprecated APIs
- **Replacement Extensions**: Find Magento 2 equivalents for incompatible extensions
- **Custom Patches**: Create patches for minor compatibility issues

### Data Migration
- **Schema Changes**: Handle database structure changes
- **Data Transformation**: Transform data to new formats
- **Custom Attributes**: Migrate custom EAV attributes
- **Media Files**: Migrate images and media files

## Best Practices

### Planning
- **Timeline Planning**: Create realistic upgrade schedules with proper testing phases
- **Risk Analysis**: Identify potential breaking changes and their business impact
- **Resource Planning**: Estimate effort, downtime, and team requirements
- **Rollback Strategy**: Plan comprehensive rollback procedures

### Execution
- **Environment Testing**: Test thoroughly in development and staging
- **Incremental Approach**: Consider incremental upgrades for major version changes
- **Documentation**: Document all changes and customizations
- **Communication**: Keep stakeholders informed throughout the process

### Post-Upgrade
- **Performance Validation**: Ensure performance meets or exceeds baseline
- **Functionality Testing**: Comprehensive testing of all features
- **Security Review**: Verify security improvements are properly implemented
- **Monitoring**: Monitor system health and performance post-upgrade

## Testing Strategy

- **Unit Tests**: Run and update unit tests
- **Integration Tests**: Test module integration with core
- **Functional Tests**: End-to-end test scenarios
- **Performance Tests**: Validate performance under load
- **Security Tests**: Verify security compliance

## References

- [Adobe Commerce Upgrade Guide](https://developer.adobe.com/commerce/operate/upgrade/)
- [Release Notes](https://devdocs.magento.com/guides/v2.4/release-notes/)
- [Migration Guide](https://developer.adobe.com/commerce/php/development/migration/)

Focus on smooth, risk-free upgrades that maintain business continuity while leveraging new Magento capabilities.

© maxnorm · MIT · maxnorm/magento2-agent-skills

Similar skills

All skills for Backend and APIs →

From the same set30

The whole set →
magento-configuration-specialist magento-configuration-specialist reads Magento 2 system configuration across default, website and store scopes, pulls setting values and checks payment, shipping and tax options. CX Codex +1 190installs magento-order-specialist The magento-order-specialist skill examines Magento 2 orders, payments, fulfillment, and processing issues. Use it when you need order details or a health check of the order flow. CX Codex +1 184installs magento-index-analyst magento-index-analyst is a Claude Code skill for Magento 2 indexing: reindexing, Elasticsearch setup, and database indexes. It addresses slow catalog browsing or search. CX Codex +1 179installs magento-deployment-engineer The magento-deployment-engineer skill designs CI/CD pipelines and automated Magento 2 deployments. Use it for infrastructure planning, containerization, and DevOps work. CX Codex +1 176installs magento-knockout-specialist magento-knockout-specialist guides coding agents in building reactive KnockoutJS UI components and MVVM patterns for Magento 2. CX Codex +1 168installs magento-environment-engineer The magento-environment-engineer skill helps manage Magento 2 across development, staging, production, and testing environments. Use it for server configuration and environment troubleshooting. CX Codex +1 168installs magento-css-specialist magento-css-specialist — a skill for building Magento 2 CSS and LESS, covering responsive themes, component styling, and CSS performance work. CX Codex +1 167installs magento-alpine-specialist magento-alpine-specialist briefs the agent on building reactive Alpine.js components for Magento 2 storefronts, Hyvä included. Handy when a template needs behaviour without a separate JS framework. CX Codex +1 166installs

Project sponsors

Companies that keep this analytics open