Clusterify.AI
© 2025 All Rights Reserved, Clusterify Solutions FZCO
I’m Calling All Magento 2 Developers and Vendors to Add SKILL.md File Their Module
How Dockerized Magento 2 Can Access Local AI and Ollama
ChatBot As A Service: Why I choose SEE over WebSocket?
Markdown vs. React for an AI ChatBot widget?
cXML 1.2 What Is New, Security And Other Changes in 2026
JWT Session Security Issue With OAuth on Mac and Chrome Browser and My Fix
Adobe, Magento partners, extension vendors, agency teams, and open-source contributors: I think it is time to start a serious discussion about adding a SKILL.md file to Magento 2 modules.
This is not just another documentation idea. It is a practical step toward making Magento modules easier for humans to understand, easier for AI tools to use correctly, and less likely to cause confusion during development, integration, debugging, and maintenance.
As AI-assisted development becomes normal across the Magento ecosystem, we need to stop thinking only in terms of PHP classes, XML, DI configuration, service contracts, and README files. We also need to think about how our modules explain themselves to intelligent tools. That is where SKILL.md can become extremely valuable. OpenAI, Anthropic, GitHub Copilot, and Microsoft now all document skills built around a SKILL.md manifest or compatible agent-skill structure, which shows this is moving into the mainstream rather than staying an experimental niche.
A SKILL.md file is a Markdown-based manifest plus instruction file that defines a reusable capability for an AI agent. In the current agent-skills ecosystem, a skill is typically a folder containing a SKILL.md file and, optionally, supporting resources such as scripts, references, templates, or examples. The file usually includes metadata such as a name and description, followed by structured instructions that explain what the skill does, when it should be used, what inputs it expects, how it should behave, and what outputs or checks it should produce.
In simpler words, SKILL.md tells an AI assistant: “When you are dealing with this kind of system, here is the right way to think about it, here are the rules, here is the workflow, and here are the mistakes to avoid.”
That matters because a Magento 2 module is rarely self-explanatory. Even well-written code often hides important assumptions that live only in a maintainer’s head.
Magento 2 is powerful, but it is also one of the most convention-heavy and misunderstanding-prone PHP platforms in common use. Small mistakes can create disproportionately large problems:
etc/adminhtml, etc/frontend, and etc/webapi_restA README.md can explain installation and usage, but it usually does not encode the deeper procedural knowledge of how the module should be modified, extended, debugged, or integrated safely. A SKILL.md can. It is designed for reusable process knowledge, not just general project description. OpenAI describes skills as a way to codify processes and conventions, while Anthropic describes them as specialized capabilities defined in Markdown that agents load when relevant.
Magento 2 modules are full of this kind of process knowledge. In fact, they are almost begging for it.
Imagine opening a Magento 2 extension and finding a SKILL.md that explains things like:
That is far more useful to an AI coding agent than a README that says “Run composer install and enable the module.”
It is also far more useful to a new developer on the team.
AI coding assistants are becoming part of daily development. But they are only as reliable as the context they receive.
Without clear guidance, an LLM may inspect a Magento codebase and make wrong assumptions. It may suggest overriding the wrong class, using an observer where a plugin would be better, bypassing service contracts, duplicating logic that already exists, or missing module-specific constraints entirely.
A SKILL.md gives the model structured project-specific guidance. This reduces ambiguity and helps the model act more like a real maintainer and less like a generic code generator. The newer skill systems from OpenAI, Anthropic, GitHub, and Microsoft all emphasize this same idea: skills package instructions, resources, and conventions so the model can perform better on specialized tasks.
There is another important detail here: modern skill systems use progressive disclosure. Instead of dumping every instruction into the context window all the time, the agent first sees lightweight metadata and only loads the full skill when it becomes relevant. OpenAI documents this behavior for Codex, and Anthropic’s materials describe a similar staged loading model. That means SKILL.md can be rich and useful without always bloating context.
For Magento, this is ideal. A skill could stay dormant until the agent detects that the task involves, for example:
At that moment, the right module-specific knowledge can load.
Most Magento problems are not caused by syntax. They are caused by misunderstanding architecture, intent, sequence, or boundaries.
That is exactly the kind of gap SKILL.md can help close.
A strong SKILL.md can tell an agent or developer:
That is gold.
It prevents costly detours. It reduces support burden. It shortens onboarding. It improves AI-generated pull requests. And it can lower the risk of bad customizations that later become production bugs.
This should not be limited to third-party vendors. Adobe should consider adding SKILL.md files to core Magento modules as well.
Why? Because core modules are exactly where developers and AI systems most often need guidance.
Magento core contains decades of accumulated design decisions, inconsistent patterns across eras, hidden assumptions, deprecated flows, and important extension boundaries that are not always obvious from code alone. If core modules exposed skill files, they could provide AI-readable guidance on intended extension mechanisms, safe customization points, deprecation expectations, testing patterns, and known architectural constraints.
That would benefit:
Core SKILL.md files could also create a de facto standard for how extension vendors should document their own modules.
In other words, Adobe could help define the AI-readable documentation layer for Magento 2.
A practical module-level SKILL.md might include sections such as:
What the module does, in precise Magento language.
Typical tasks, such as adding a field, extending an API, debugging totals, or integrating a frontend component.
Key services, repositories, XML files, events, plugins, consumers, cron jobs, UI components, and extension points.
What to extend, what not to override, and preferred patterns.
Known failure modes and misleading assumptions.
Which cache flushes, reindexes, deployment steps, and tests matter after changes.
Magento Open Source vs Adobe Commerce, MSI dependencies, PHP version assumptions, third-party conflicts, or edition-specific behavior.
“How to add a new config field safely,” “How to expose a REST endpoint,” “How to extend order data,” and so on.
This would be enormously useful in real projects.
This idea is timely because the broader ecosystem is already moving in this direction.
OpenAI documents skills as reusable bundles anchored by a SKILL.md manifest and notes that they are compatible with the open Agent Skills standard. Anthropic documents a similar model for Claude Code, where a SKILL.md file adds a new capability to the toolset. GitHub Copilot now supports agent skills, and Microsoft’s Agent Framework also documents agent skills as portable packages following an open specification.
There are also a few interesting quantitative signals around the format and its usage patterns:
OpenAI’s public openai/skills repository already exposes a sizable catalog of curated and experimental skills, and Anthropic’s public skills materials recommend keeping always-loaded metadata small while loading the full body only when needed. Anthropic’s example guidance describes a three-level loading system where metadata is always present and the full SKILL.md loads only when triggered.
Beyond the core vendors, one ecosystem article describes skill.md as installable into “20+ major coding agents,” while an adjacent AGENTS.md convention is described as being used across “60,000+ open-source projects.” That second number is about AGENTS.md, not SKILL.md, so it should not be conflated, but together they do suggest that machine-readable guidance files are moving quickly from experiment to convention.
So even if Magento has not standardized this yet, the direction of travel is clear.
Extension vendors often spend huge time on support tickets that are really documentation failures in disguise.
A merchant’s agency integrates the module incorrectly.
A developer overrides the wrong class.
A team assumes the module supports a flow it never intended to support.
An AI assistant generates code that “looks Magento-ish” but violates the vendor’s architecture.
A good SKILL.md can reduce all of that.
It becomes a bridge between code, docs, maintainers, and AI tools.
It can also become a competitive advantage. Vendors who provide AI-readable module guidance may see:
In a world where more code is first drafted with AI, the modules that explain themselves best may win.
I would love to see the Magento community define a lightweight convention, something like:
Vendor/Module/SKILL.md
Or perhaps:
docs/SKILL.md
With optional supporting files such as:
docs/architecture.mddocs/troubleshooting.mddocs/examples/add-new-attribute.mddocs/examples/extend-api.mdEven a minimal standard would help if it answered a few key questions consistently:
That alone would make many Magento projects safer.
I believe SKILL.md could become one of the most practical new documentation layers for Magento 2.
Not flashy.
Not theoretical.
Just useful.
It can help AI tools understand modules more accurately.
It can help developers avoid mistakes.
It can help vendors communicate architectural intent.
It can help Adobe make core Magento easier to extend safely.
And it can help the whole ecosystem move toward clearer, more maintainable, AI-ready engineering.
So this is my call to action:
Adobe, Magento partners, extension vendors, agencies, and open-source maintainers: let’s start discussing whether every serious Magento 2 module should ship with a SKILL.md file.
Because the future is not just code that runs.
It is code that can explain itself clearly to both humans and machines.