From Magento 2 / Mage-OS Skills
Correct Magento 2 / Mage-OS / Adobe Commerce module development: scaffolding new modules, extending or customizing core behavior (plugin vs observer vs preference decisions), declarative schema and custom tables, product/EAV attributes, dependency injection, checkout/cart/totals and custom order or shipping fee logic, admin configuration (system.xml/ACL), admin grids and ui_components, layout XML and view models, upgrading or migrating custom modules (incl. to Mage-OS) and their composer.json constraints, and debugging playbooks for setup:di:compile failures, layout not applying, and observers/plugins that don't fire. Use this skill whenever the user is writing, modifying, or debugging custom Magento, Mage-OS, or Adobe Commerce code — creating or extending a module/extension, intercepting core behavior, adding database tables or attributes, building admin settings or grids, frontend blocks or templates, or fixing errors from bin/magento commands — even if they don't say "module" explicitly. Strong triggers: "how do I override X in Magento", "my Magento layout/plugin/observer isn't working", "do I use an observer or a plugin", or anything touching app/code, di.xml, events.xml, db_schema.xml, or layout XML. Do NOT trigger for storefront performance/cache audits (use the magento-audit skill), buying or recommending third-party extensions, operational admin tasks (creating coupons, importing product CSVs, session/login settings), Magento hosting/sizing questions, content/SEO copy, or non-Magento platforms like Shopify or WooCommerce.
How this skill is triggered — by the user, by Claude, or both
Slash command
/magento-skills:magento-moduleThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Expertise for writing Magento 2 modules that compile, pass `phpcs --standard=Magento2`, and
Expertise for writing Magento 2 modules that compile, pass phpcs --standard=Magento2, and
follow current (2.4.x / Mage-OS) conventions. Magento has accumulated a decade of outdated
tutorials; this skill exists because the obvious approach found in old blog posts is often
wrong today. When in doubt, prefer the conventions here over patterns seen in older code.
These are the mistakes that get extensions rejected from the marketplace and break upgrades:
ObjectManager::getInstance() in your own code. Constructor injection only.
ObjectManager hides dependencies, breaks compilation analysis, and fails code review.
(Exceptions: factories/proxies generated by Magento may use it internally — that's fine.)db_schema.xml), never InstallSchema/UpgradeSchema scripts.
Install scripts have been deprecated since 2.3 and make schema state unauditable.$escaper->escapeHtml() / escapeHtmlAttr() /
escapeUrl(). Unescaped echo in .phtml is an XSS finding.Api/ interfaces (e.g. ProductRepositoryInterface),
not concrete Model classes, when consuming other modules.etc/di.xml vs etc/frontend/di.xml vs
etc/adminhtml/di.xml. A frontend-only plugin registered globally slows down everything.Identify the task type and read the matching reference before writing code:
| Task | Read first |
|---|---|
| Change/intercept core behavior | references/extension-mechanisms.md |
| New module from scratch | this file + run scripts/scaffold.py |
| Database tables / columns | references/declarative-schema.md |
| DI wiring, virtual types, factories, proxies | references/di-patterns.md |
| Admin settings, grids, menus, ACL | references/admin-ui.md |
| Frontend pages, blocks, templates, layout | references/frontend.md |
| REST / GraphQL / web APIs | references/api.md |
| CLI commands, cron jobs, message queues | references/cli-cron.md |
| Writing unit / integration tests (PHPUnit) | references/testing.md |
| Errors, "not working", compile failures | references/debugging.md |
For a new module, scaffold the boilerplate with the script — it is deterministic and avoids typos in XML namespaces that cost a compile cycle to discover:
python scripts/scaffold.py Vendor_Module --path app/code [--description "..."] \
[--sequence Magento_Catalog,Magento_Checkout]
This emits registration.php, etc/module.xml, and composer.json. Everything else
(di.xml, plugins, schema, layout) you write by hand following the references — those
parts need judgment, the boilerplate doesn't.
Implement the business logic. Keep each class small; one responsibility per plugin
or observer. Name plugins descriptively (<type name="..."><plugin name="acme_add_gift_label" .../></type> —
the name is global, so prefix with the vendor).
Verify before declaring done. From the Magento root:
bin/magento module:enable Vendor_Module
bin/magento setup:upgrade # registers module, applies db_schema
bin/magento setup:di:compile # catches DI mistakes; must pass
vendor/bin/phpcs --standard=Magento2 app/code/Vendor/Module # if installed
bin/magento cache:flush
If setup:di:compile fails, go to the debugging reference — the error messages are
cryptic but mechanical to resolve. Do not hand unverified code back to the user when a
Magento installation is available to compile against.
Api/ interface) first, then
webapi.xml or schema.graphqls (references/api.md) — never expose a Model.Before finishing any task, run through references/checklists.md
— it covers cache tags, ACL coverage, i18n (__() + i18n/en_US.csv), escaping, and the
composer/module.xml consistency checks that reviewers look for.
Mage-OS is a community fork, drop-in compatible with Magento 2.4.x. Code targeting Magento
2.4 works unchanged. In composer.json, depend on magento/framework version ranges (the
Mage-OS packages provide/replace them) rather than pinning magento/product-community-edition.
If the elgentos magento2-dev-mcp MCP server is connected, prefer it for reading merged
configuration (effective di.xml, layout) instead of reasoning from single files — Magento
merges XML across modules and the single-file view misleads.
npx claudepluginhub staksoft/magento-claude-skills --plugin magento-skillsProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.