data-migration
/data-migration
Generate Magento 2 data migration code — data patches for fixed seeds, importers for CSV/JSON sources, and transformation scripts. Use when the user needs to seed reference data, migrate from Magento 1, import bulk data from external systems, or restructure existing data idempotently. Produces idempotent patches that pass magento2-tools:review. For adding an EAV attribute use magento2-tools:eav-attribute.
- Author
- muon-m2 ↗
- Repository
- magento2-tools ↗
- Licence
- MIT
- Last repository change
- 04.10.2026
Assessment and security
- Files in this package
- 11
- Scripts
- 5
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 04.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 5 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: templates/data-patch-bulk-import.php, templates/data-patch-fixed-seed.php, templates/data-patch-transformation.php, templates/import-cli-command.php, templates/importer-service.php
What it does and when to use it
Generate Magento 2 data migration code — data patches for fixed seeds, importers for CSV/JSON sources, and transformation scripts. Use when the user needs to seed reference data, migrate from Magento 1, import bulk data from external systems, or restructure existing data idempotently. Produces idempotent patches that pass magento2-tools:review. For adding an EAV attribute use magento2-tools:eav-attribute.
Original author description
Generate Magento 2 data migration code — data patches for fixed seeds, importers for CSV/JSON sources, and transformation scripts. Use when the user needs to seed reference data, migrate from Magento 1, import bulk data from external systems, or restructure existing data idempotently. Produces idempotent patches that pass magento2-tools:review. For adding an EAV attribute use magento2-tools:eav-attribute.
How it works
- Core Rules
- Workflow
- Inputs
- Outputs
- Reference Files
- Templates
- Acceptance Criteria
- Related Skills
SKILL.md preview
---
name: data-migration
version: 1.3.2
description:
Generate Magento 2 data migration code — data patches for fixed seeds, importers for
CSV/JSON sources, and transformation scripts. Use when the user needs to seed reference
data, migrate from Magento 1, import bulk data from external systems, or restructure
existing data idempotently. Produces idempotent patches that pass magento2-tools:review. For
adding an EAV attribute use magento2-tools:eav-attribute.
---
# Magento 2 Data Migration
Generate data patches, importer services, and transformation scripts.
## Core Rules
- **Idempotent.** Re-running `setup:upgrade` must NOT duplicate data. Check for existing
state before inserting.
- **DataPatchInterface only.** No legacy `Setup/InstallData.php` or `UpgradeData.php`.
- **Chunked for bulk.** Imports of > 100 rows must process in batches of ≤ 500.
- **Transactional for transformations.** SELECT → INSERT → DELETE wrapped in a single
DB transaction (where possible).
- **Reversible when feasible.** Patches that delete data must document the rollback path
(or refuse to delete without `--allow-destructive`).
- **Test-first for the data effect.** Write the failing integration test before the patch body
(red → green → refactor) and **watch it fail for the right reason**. The test asserts the
post-migration state and, critically, **idempotency** (apply twice → identical state). The
patch exists only to turn that test green. See `context/references/tdd-discipline.md`.
A patch is exempt only when it is pure config with no data effect — document why.
- **Coding style.** Generated PHP follows PER-CS 3.0 as the baseline, with the Magento 2 coding
standard taking precedence on any conflict; `--standard=Magento2` PHPCS is the gate. See
`context/references/php-coding-style.md`.
- **Source of truth.** Generate from templates → shared references → baked-in Magento 2 knowledge
→ official Magento/Adobe docs (live-fetched only when uncertain). Do NOT read, grep, or "study"
other modules under `app/code`/`vendor/*`/Magento core to infer conventions, entity shapes,
naming, or wiring. Narrow exceptions: the target module/class of this operation, and the specific
contract of a module this code explicitly depends on. Affirm sources in the final report. See
`context/references/source-of-truth.md`.
## Workflow
### Phase 0 — Context Resolution
Invoke `context`.
### Phase 1 — Plan
Determine migration class:
| Class | When |
|-------|------|
| Fixed seed | Small, known data (< 100 rows hard-coded in PHP) |
| Bulk import | CSV/JSON, > 100 rows from an external source |
| Transformation | Move/rename existing data inside Magento |
Ask the user for:
- Data source (file path, API endpoint, M1 DB connection details)
- Target tables / entities
- Idempotency strategy (hash, unique constraint, lookup-then-insert)
- Whether rollback is required
### Phase 2 — Test First, then Generate
**2A — Write the failing test (RED).** Before any patch code, add an integration test under
`Test/Integration/` that asserts the post-migration state **and idempotency** (run the patch
twice → identical rows, no duplicates, no error). Start from
`test-generate/templates/test-integration-data-patch.php` and follow
`context/references/tdd-discipline.md`. Run it and **confirm it fails for the right
reason** (data absent / patch class missing) — not a setup or missing-class error. If no Magento
test DB is available, follow the *tiered fallback* in `tdd-discipline.md`: write a test-first
**unit** test of the importer's idempotency guard (lookup-then-insert) instead, and record the
integration gap in the Phase 4 report.
**2B — Generate the patch (GREEN).** Write the minimal patch needed to turn 2A green:
#### Fixed seed
- `Setup/Patch/Data/{Name}.php` with the data inline.
#### Bulk import
- `Setup/Patch/Data/{Name}.php` invoking…
- `Service/Importer/{Name}Importer.php` — chunked processing, idempotency checks
- Optional `Console/Command/{Name}Command.php` — CLI entry point
(`bin/magento {vendor}:{module}:import [--dry-run]`)
#### Transformation
- `Setup/Patch/Data/{Name}.php` with SELECT → INSERT → DELETE inside a transaction.
- Idempotency: check whether destination already has the migrated row before inserting.
**2C — Refactor.** With the test green, tidy only what you touched; keep it green.
### Phase 3 — Verify
- `php -l` on each file.
- Run the Phase 2A test with `{ctx.runner} vendor/bin/phpunit` and confirm it now **passes**
(it failed before 2B). Run the affected module's suite to confirm nothing else broke.
- Dry-run: optional `--dry-run` flag on generated CLI command outputs what would be
imported without writing.
- **Apply the shared module-hygiene baseline (required).** After generating or modifying
PHP files, run
`${CLAUDE_PLUGIN_ROOT}/skills/context/scripts/add-license-headers.sh {ctx.magento_root}/app/code/{Vendor}/{Module} {Vendor}`
to stamp the standard copyright header onto every new `.php` (idempotent — it skips files
that already carry it). When adding a `composer.json` `require` entry, resolve a
**bounded** constraint via
`${CLAUDE_PLUGIN_ROOT}/skills/context/scripts/resolve-dep-constraint.sh <vendor/package>` —
never `"*"`. See `context/references/module-hygiene.md`.
### Phase 4 — Report
Save to `{output_root}/migrations/{name}-{date}.md`:
- Source described
- Target tables / entities
- Idempotency strategy
- Test path + red→green evidence (or the recorded integration gap if a test DB was unavailable)
- Re-run safety statement
- Rollback statement (if feasible)
- Migration command for the user to run
> **Docs may now be stale.** This change modified module code. Run
> `docs --module={Vendor}_{Module}` to refresh the module's README,
> CHANGELOG, and `docs/*.md` (technical reference, guides, and API references as
> applicable).
## Inputs
```
/data-migration --type=seed|import|transform [source flags] [--docs-root=<path>]
```
`--docs-root=<path>` — output-root override; see "Output root" below.
## Outputs
```
{ctx.magento_root}/app/code/{Vendor}/{Module}/Setup/Patch/Data/{Name}.php
{ctx.magento_root}/app/code/{Vendor}/{Module}/Service/Importer/{Name}Importer.php # if import
{ctx.magento_root}/app/code/{Vendor}/{Module}/Console/Command/{Name}Command.php # if CLI
{ctx.magento_root}/app/code/{Vendor}/{Module}/Test/Integration/Setup/Patch/Data/{Name}Test.php # test-first (Phase 2A)
{output_root}/migrations/{name}-{date}.md
```
`{output_root}` defaults to `.docs` (`{ctx.docs_root}`), anchored at the project root, never
under `{ctx.magento_root}`, `app/code`, or a module dir. See the **Artifact location** rule in
`context/SKILL.md`.
### Output root (`--docs-root`)
This skill accepts `--docs-root=<path>` (see
`context/references/artifact-layout.md`). When set, write the run report (and any
report artifacts) under `<path>/migrations/`; otherwise default to
`{ctx.docs_root}/migrations/`. `feature` passes this so a feature run's
reports collect under its folder.
## Reference Files
- `references/data-patch-rules.md` — DataPatchInterface idempotency rules.
- `references/importer-patterns.md` — chunked import patterns.
- `references/m1-to-m2-map.md` — common Magento 1 → 2 transformations.
- `references/idempotency-strategies.md` — hash-based, unique-constraint, lookup-then-insert.
- `references/rollback-strategies.md` — when rollback is feasible; how to implement.
- `context/references/tdd-discipline.md` — shared test-first loop; the Phase 2A test
reuses `test-generate/templates/test-integration-data-patch.php` as its skeleton.
- `context/references/source-of-truth.md` — source-of-truth hierarchy + the
no-unrelated-module-scanning rule (allowed reads, live-doc fetch protocol, report affirmation).
## Templates
- `templates/data-patch-fixed-seed.php`
- `templates/data-patch-bulk-import.php`
- `templates/data-patch-transformation.php`
- `templates/importer-service.php`
- `templates/import-cli-command.php`
## Acceptance Criteria
- All generated patches implement `DataPatchInterface` and `getDependencies()`.
- All patches are idempotent.
- A test asserting **idempotency** (apply twice → identical state) was written and **watched to
fail** before the patch existed, and passes after (integration when a test DB is available;
otherwise a test-first unit test of the idempotency guard, with the integration gap recorded).
- For bulk imports, processing is chunked (default 500 rows).
- For transformations, source data is preserved until destination is verified.
## Related Skills
| Phase | Skill |
|-------|-------|
| 0 | `context` |
| (after Phase 2) | `review` for the affected module |
Files in this package (11)
- SKILL.md 9 KB
- references/data-patch-rules.md 3 KB
- references/idempotency-strategies.md 3 KB
- references/importer-patterns.md 4 KB
- references/m1-to-m2-map.md 3 KB
- references/rollback-strategies.md 3 KB
- templates/data-patch-bulk-import.php 2 KB
- templates/data-patch-fixed-seed.php 2 KB
- templates/data-patch-transformation.php 4 KB
- templates/import-cli-command.php 2 KB
- templates/importer-service.php 4 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · muon-m2/magento2-tools | 100 | MIT |
| TerminalSkills/skills | 100 | Apache-2.0 |
| uw-ssec/rse-plugins | 95 | BSD-3-Clause |
| cbrock84/headcount | 90 | MIT |
| arjunprabhulal/devops-skills | 90 | MIT |
Database snapshot: 13.11.2026 · package version 5d7a4a0f02bc (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100eav-attribute
Add a Magento 2 EAV attribute (product, customer, customer-address, or category) via an idempotent data patch. Use when the user wants to add a product/customer/category attribute. Handles scope (global/website/store), input type, backend/source/frontend models, indexer… - 90magento-eav-attributes
Work with Magento 2 EAV (Entity-Attribute-Value) system — create custom attributes, attribute sets, manage EAV tables, and understand the EAV data model. Use when adding product/category/customer attributes or working with the attribute system. - 100module-create
Create a new Magento 2 module under the project's vendor namespace. Use when asked to create, scaffold, generate, or build a Magento 2 module, extension, component, or package. Generated files pass all 12 magento2-tools:review categories. Surface-driven: creates only files for… - 100magento-module-dev
Create Magento 2 custom modules — registration, directory structure, models, resource models, collections, declarative schema, and data/schema patches. Use when building new modules or understanding module architecture. - 100frappe-data-migration-generator
Generate data migration scripts for Frappe. Use when migrating data from legacy systems, transforming data structures, or importing large datasets. - 100frappe-data-migration-generator
Generate data migration scripts for Frappe. Use when migrating data from legacy systems, transforming data structures, or importing large datasets.