Add AGENTS.md + 27 OpenMage Agent Skills for Claude Code (and other agents)#5555
Add AGENTS.md + 27 OpenMage Agent Skills for Claude Code (and other agents)#5555colinmollenhour wants to merge 11 commits into
Conversation
There was a problem hiding this comment.
Pull request overview
Adds agent-facing documentation to help coding agents (Claude Code, Cursor, Copilot Workspace, etc.) work safely and consistently in the OpenMage / Magento LTS codebase.
Changes:
- Adds a repo-root
AGENTS.mdas the always-loaded “north star” for agent workflows and project conventions. - Adds 27 Claude Agent Skills under
.claude/skills/**/SKILL.md, organized by framework mechanics, domain modules, and tooling/quality topics. - Documents operational workflows for tooling (PHPStan, PHPUnit, Rector) and vendor patching.
Reviewed changes
Copilot reviewed 28 out of 28 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| AGENTS.md | Agent guide: project overview, BC rules, commands, architecture notes, and conventions. |
| .claude/skills/m1-acl-adminhtml/SKILL.md | Agent skill: Magento 1 admin ACL concepts and wiring. |
| .claude/skills/m1-api-soap-rest/SKILL.md | Agent skill: Magento 1 SOAP/XML-RPC and REST (Api2/OAuth) concepts. |
| .claude/skills/m1-caching/SKILL.md | Agent skill: cache types, tagging, invalidation, and block caching. |
| .claude/skills/m1-controllers-routing/SKILL.md | Agent skill: controller structure, routing, lifecycle, and form-key patterns. |
| .claude/skills/m1-db-setup-scripts/SKILL.md | Agent skill: install/upgrade scripts, version bumps, and EAV setup. |
| .claude/skills/m1-eav/SKILL.md | Agent skill: Magento 1 EAV mechanics and common patterns. |
| .claude/skills/m1-events-observers/SKILL.md | Agent skill: event dispatch/observer registration and area scoping. |
| .claude/skills/m1-indexers-cron/SKILL.md | Agent skill: indexer registration/modes and cron scheduling lifecycle. |
| .claude/skills/m1-layout-blocks/SKILL.md | Agent skill: layout XML, blocks, templates, fallback, and template PHPStan implications. |
| .claude/skills/m1-module-structure/SKILL.md | Agent skill: module activation, config.xml, aliases/rewrites, and area scoping. |
| .claude/skills/m1-system-config/SKILL.md | Agent skill: system.xml, scopes, backend/source models, encrypted config. |
| .claude/skills/m1-translations/SKILL.md | Agent skill: CSV translations, __() binding, and JS translator config. |
| .claude/skills/mage-adminhtml/SKILL.md | Agent skill: adminhtml module concepts and common extension points. |
| .claude/skills/mage-catalog/SKILL.md | Agent skill: catalog models, URL rewrites, indexing, and flat/EAV pitfalls. |
| .claude/skills/mage-checkout/SKILL.md | Agent skill: checkout flows, quote session behavior, and conversion handoff. |
| .claude/skills/mage-cms/SKILL.md | Agent skill: CMS pages/blocks/widgets and directive rendering. |
| .claude/skills/mage-customer/SKILL.md | Agent skill: customer EAV, sessions, login flow, hashing, groups. |
| .claude/skills/mage-payment-methods/SKILL.md | Agent skill: payment method capabilities, info storage, IPN/webhook patterns. |
| .claude/skills/mage-product-types/SKILL.md | Agent skill: configurable/grouped/bundle/downloadable internals and cart payloads. |
| .claude/skills/mage-promotions/SKILL.md | Agent skill: catalog vs sales rules, rule DSL, coupon generation, reindex needs. |
| .claude/skills/mage-sales/SKILL.md | Agent skill: quote→order lifecycle, totals collectors, order states/statuses. |
| .claude/skills/mage-shipping-carriers/SKILL.md | Agent skill: carrier registration, rate pipeline, free-shipping interactions. |
| .claude/skills/mage-tax/SKILL.md | Agent skill: tax calculation pipeline, algorithms, display matrix, Weee/FPT. |
| .claude/skills/phpstan-magento1/SKILL.md | Agent skill: PHPStan posture, plugin behavior, baselines, common pitfalls. |
| .claude/skills/phpunit-openmage-tests/SKILL.md | Agent skill: OpenMage PHPUnit conventions, base class, providers, isolation. |
| .claude/skills/rector-openmage/SKILL.md | Agent skill: Rector config/presets, custom migration rules, skip list. |
| .claude/skills/vendor-patches/SKILL.md | Agent skill: vendor patch workflow via patches.json/.vendor-patches. |
|
I'll have a good play with this, have built out a similar CLAUDE.md / skills layout for our store so will be interesting to get a comparison. First thing off the bat - Anthropic Agent Skills doesn't exist anymore looks like. |
Great, looking forward to your feedback. Feel free to also push improvements directly here if you like. This is just the first pass, I'll try to get around to making a second pass; I have a "skills audit" that I'll dig up and adapt, it works very well (the first pass of such large skills files often has lots of hallucinations). But in my experience the skills can make a big difference once they are of high quality.
Hah, good catch. This must have come from my skill-writer skill that is out of date.. Seems like nobody cares to do redirects anymore these days.. :/ |
That's one question.. how do we include this in the repo? Should it just be right there in the root, or should it instead be published to a marketplace/plugin? |
…ine header Repo bumped PHPStan to level 8 in OpenMage#5542; AGENTS.md and the affected skills still referenced level 6. Also drops the stale "23693 errors" total from the phpstan-magento1 skill — `_loader.php` is just an include list with no header. Addresses Copilot review feedback on PR OpenMage#5555. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Comments addressed: 5 / 5 (all fixed)
State: branch head is |
Any place/idea where it could published to? imho its fine to have it in root/project. ideas
|
Adds .claude-plugin/marketplace.json + .claude/.claude-plugin/plugin.json so the existing 27 skills under .claude/skills/ can be installed via `/plugin marketplace add OpenMage/magento-lts` and the plugin name `openmage-skills@openmage`. Project-local skill auto-load is unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Just pushed Install in Claude CodeInside an interactive Claude Code session: Or non-interactively from a shell: claude plugin marketplace add OpenMage/magento-lts
claude plugin install openmage-skills@openmageUpdates land via Install in any other agent (Cursor, Codex, OpenCode, …) — and Claude Code without the marketplace
# preview
bunx skills add OpenMage/magento-lts --list
# install all 27
bunx skills add OpenMage/magento-lts --all
# or pick one
bunx skills add OpenMage/magento-lts --skill openmage-eav
# target a specific agent (otherwise it auto-detects)
bunx skills add OpenMage/magento-lts -a cursor -a claude-code
|
... does not exist. Its CatalogRule ... |
So the convex project have a great way using their convex cli to manage it and a skills-lock.json so the managing of skills / ai files is outside the main repo and the tooling is part of the main 'binary'. That wouldn't work so cleanly here as we dont have a blessed openmage cli tool (magerun prob will fit the bill as it's adopted to be more openmage specific in 3+ versions). Then you'd have magerun dev:skills:install magerun dev:skills:update and so forth and have it manage the install that way. Also allows the skills / ai files to update far more regularly than the core project, though you then have versioning issues i suppose. https://docs.convex.dev/ai/agent-skills At the bottom of one of our apps' CLAUDE.md, convex skills adds a demarked portion This project uses Convex as its backend. When working on Convex code, always read Convex agent skills for common tasks can be installed by running I quite like this approach, though it has to be said there's already one issue in that we mandate pnpm over npx so even that little snippet is subtly wrong. |
I don't think it hallucinated in this case, it just seems to have bundled Mage_CatalogRule, Mage_SalesRule and core Mage_Rule modules into one under that general title. You think it would be better named mage-module-rule? |
Verified every factual claim in each SKILL.md against the codebase and applied surgical fixes for ~157 findings: factually wrong method names, fabricated APIs, wrong indexer aliases, stale event names, inverted semantics, and assorted wording precision issues. Highlights: - mage-module-cms: corrected router target, dropped non-existent _addAfterFilterCallback, fixed widget instance ACL path, real page_groups enum, real <tempate_filter> typo - mage-module-product-types: removed swatch_image/swatch_thumb (M2 concepts), real canUseAttribute() rules, sales_order_save_commit_after - mage-module-customer: default_billing/_shipping are EAV attrs not columns, group_id (not customer_group_id), corrected SHARE_GLOBAL/ SHARE_WEBSITE polarity - mage-module-payment-methods: dropped fabricated Centinel MethodInterface, real Centinel auth URLs, payment_transaction schema, distinguished _canCreateBillingAgreement vs interface - mage-module-sales: corrected sales_payment_transaction table name, service_order::prepareInvoiceCreditmemo, dropped phantom sales_order_state_change_before event, shipment-vs-invoice independence - mage-module-shipping-carriers: rate pipeline order, USPS uses <environment> (not <mode>), real getUps* getters - openmage-eav: composite UNIQUE columns, _isAttributeValueEmpty() location, _storeValuesFlags semantics, addFieldToFilter behavior - openmage-indexers-cron: removed fabricated catalogrule_product indexer, real index_event schema columns, --reindexallrequired semantics, process state labels - openmage-layout-blocks: jsQuoteEscape (not escapeJsQuote), removed nonexistent escapeUrlAttribute, __() escaping reality - openmage-module-structure: fixed malformed XML closing tags, real community modules list, MAGE_MODULES order, no alphabetical merge - phpstan-magento1: dynamicCallOnStaticMethod via strict-rules (not bleedingEdge), per-identifier baselines (not globally suppressed), variable.undefined exemption (not empty.notAllowed), no _init() plugin handling - rector-openmage: PHP set scope, ArrayFirstLastRector behavior, Zend_Log → Monolog (not Laminas), Zend_Measure → Mage helpers, RenameClassAndConstFetch (not RenameClassConstFetch) Audited via /openmage-skills:audit; fixes applied via Python exact-string replacement with manual review per finding.
I think (no, its not important) |
|
Better dont get lost in details. Approved. |
|
@colinmollenhour pls merge your own. |
|
To mitigate concerns of these files interfering with other people's files I've added archive.exclude to the composer.json and also excluded a bunch of other files that don't need to be in the composer package (docs, tests, CNAME, dotfiles). Also added a docs page with instructions for installing the skills (for people using the composer install since even without excluding them from the package it's likely they won't be useful in the vendor/ directory. So I think that resolves my concerns with objections people might have had and nobody else has objected. :) |
Surgical fixes from a verification pass against the actual codebase: exception class names, method default values, default-route resolution, default cache backend, getCheckout() topology, _canReviewPayment behavior, Zend rename targets (Monolog/Mage_Core_Helper, not laminas/Carbon), dynamicCallOnStaticMethod attribution (strict-rules, not bleedingEdge), and ~20 other minor factual corrections. Nine skills passed clean. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…s from Composer package
Maybe it should be clarfied (not only for AI) that migration rules are here to update 3rd-party-code as well.
|
|
Summary
Adds two pieces of agent-facing tooling to the repo:
AGENTS.mdat the repo root — an always-loaded north-star document for any code-writing agent (Claude Code, Cursor, Copilot Workspace, Codex, etc.) describing repo conventions, BC rules, where the source of truth lives, and the project's stance on observers vs. rewrites vs. core edits..claude/skills/— 27 OpenMage Agent Skills organized in three tiers:m1-module-structure,m1-events-observers,m1-layout-blocks,m1-controllers-routing,m1-system-config,m1-acl-adminhtml,m1-eav,m1-db-setup-scripts,m1-api-soap-rest,m1-indexers-cron,m1-caching,m1-translations.mage-catalog,mage-sales,mage-checkout,mage-customer,mage-adminhtml,mage-promotions,mage-payment-methods,mage-shipping-carriers,mage-tax,mage-cms,mage-product-types.phpunit-openmage-tests,phpstan-magento1,rector-openmage,vendor-patches.These follow the Anthropic Agent Skills format (a
SKILL.mdper skill with YAML frontmatter declaringname,description, and trigger conditions, plus dense reference content). They live under.claude/skills/so Claude Code picks them up automatically; nothing else in the repo loads or depends on them, so non-Claude agents and humans can ignore them. Skills are layered (each cross-references neighbors with a See also block) so loading e.g.mage-promotionsbrings the right adjacent context (mage-sales,m1-events-observers,m1-indexers-cron) into scope by name.How this was generated
Authored interactively with Claude (Sonnet/Opus 4.x) over several sessions, following a repo-tailored authoring loop:
SKILLS-WISHLIST.md(kept locally, not in this PR) enumerated the candidate skills, grouped by tier, with one-line scope notes per skill — to keep boundaries clean before any prose was written.app/code/core/Mage/<Module>/files (and the shared lib code where relevant), then summarising the non-obvious parts: tables, model lifecycle, area scoping, observer event names, indexer dependencies, gotchas. Things derivable from a singlegrepwere left out; the goal is to stash the knowledge that's expensive to re-derive, not duplicate the codebase.The total cost (Anthropic API spend) to generate the skill set was modest — well under what a single review cycle by an experienced contributor would cost — and the corpus is now reusable for any future agent run on this repo.
Why this is useful
salesrule/bug has to spend a chunk of context window doing exploratorygrepand reading several files just to recall howMage_SalesRule_Model_Validatorinteracts withQuote_Discountand the rule DSL. With the skill loaded, that context is one tool call instead of fifteen — and the agent reads the correct mental model up front rather than reverse-engineering it from a partial sample of the source._eventPrefixsemantics, indexer reindex-vs-event timing,dynamicCallOnStaticMethodPHPStan trap. An agent that has read these is much less likely to ship the kind of change that technically works but creates a maintenance hazard.Mage_Sales_Model_Orderchanges, the matching skill (mage-sales) is right there to be updated as part of the same PR — no separate wiki to drift out of sync..claude/; not autoloaded, not deployed, not parsed by Magento.How well does it actually work?
Three small bug-fix PRs were authored end-to-end by Claude using only these skills (no human pre-review of the diffs, just verification afterwards). Each PR's description lists exactly which skills the agent loaded for the task — useful as a calibration signal for skill triggering:
mage-promotions.mage-product-types.mage-promotions+m1-events-observers.Each fix is small, targeted, and lands in the right model with the right idioms. Reviewers may want to look at those PRs alongside this one.
Compatibility / opt-out
.claude/entirely — it's gitignored by most non-Claude workflows already, and there's no build step or runtime hook.SKILL.mdfiles into their own format or read them as-is — they're plain Markdown.Test plan
This PR is documentation only. There are no source / config / test changes that affect runtime behavior.
.claude/skills/<name>/SKILL.mddiscovery).main(the three reference PRs above effectively did this formage-promotions,m1-events-observers, andmage-product-types).git ls-files .claude/lists the 27 SKILL.md files.🤖 Authored with Claude Code