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
npx skills add maxnorm/magento2-agent-skills --skill magento-upgrade-specialist -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/magento-upgrade-specialist/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/magento-upgrade-specialist/
1Skills CLI (Vercel)
npx skills add maxnorm/magento2-agent-skills --skill magento-upgrade-specialist -a codex2Manually: put the files in place
.agents/skills/magento-upgrade-specialist/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add maxnorm/magento2-agent-skills --skill magento-upgrade-specialist -a cursor2Manually: put the files in place
.cursor/skills/magento-upgrade-specialist/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install maxnorm/magento2-agent-skills skills/magento-upgrade-specialist2Manually: put the files in place
.github/skills/magento-upgrade-specialist/SKILL.md1Skills CLI (Vercel)
npx skills add maxnorm/magento2-agent-skills --skill magento-upgrade-specialist -a gemini-cli2Platform CLI
gemini skills install https://github.com/maxnorm/magento2-agent-skills --path skills/magento-upgrade-specialistManually: put the files in place
.devin/skills/magento-upgrade-specialist/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add maxnorm/magento2-agent-skills --skill magento-upgrade-specialist -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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