README

Magento AI Toolkit is a Composer plugin that installs project-level AI instructions and Magento-focused skills into a Magento codebase. It gives compatible coding agents a consistent set of architecture, coding, testing, cache, database, and delivery rules without requiring each project to maintain those files manually.

Requirements

PHP 8.5
Composer 2 with composer-plugin-api 2.x
Magento Open Source or Adobe Commerce 2.4.9 project structure
Write access to the Magento root directory

The package does not execute Magento setup commands and does not modify Magento application code.

Installation

Run these commands from the Magento Composer root, where the main composer.json is located:

composer config allow-plugins.mar-pod/magento-ai-toolkit true
composer require mar-pod/magento-ai-toolkit:^1.1

Composer activates the plugin during installation. The plugin then creates or updates its managed resources in the Magento root.

Installed files

AGENTS.md
.agents/
├── rules/
│   ├── PROJECT_RULES.md
│   └── CODING_STANDARDS.md
└── skills/
    ├── magento-admin-ui/
    ├── magento-bug-triage/
    ├── magento-cache-development/
    ├── magento-code-review/
    ├── magento-database-schema/
    ├── magento-indexer-development/
    ├── magento-observer-development/
    ├── magento-plugin-development/
    ├── magento-project-development/
    └── magento-testing/

Each skill contains a SKILL.md and UI metadata under agents/openai.yaml.

How it works

The Composer plugin runs during activation and synchronizes the packaged rules/ and skills/ resources into .agents/ in the consuming project.

If AGENTS.md does not exist, the plugin creates it. If it already exists, the plugin preserves the existing content and appends one managed block with links to the installed rules and skills. Repeated Composer runs do not duplicate that block.

The plugin owns only:

its marked block inside AGENTS.md;
rule files supplied by this package;
skill directories supplied by this package.

Other content in AGENTS.md and unrelated files under .agents/ are preserved.

Configuration

The plugin has no runtime configuration or Magento Admin settings. Its behavior is defined by the versioned resources included in the package.

Composer must explicitly allow the plugin:

{
    "config": {
        "allow-plugins": {
            "mar-pod/magento-ai-toolkit": true
        }
    }
}

The setting is global to the Composer project and has no Magento configuration scope.

Updating

Update the toolkit from the Magento Composer root:

composer update mar-pod/magento-ai-toolkit

During activation, the plugin refreshes its managed rules and skills while preserving unrelated project files.

Stable releases follow Semantic Versioning. Published stable tags are immutable and must never be moved or recreated on another commit.

Local package development

Clone the repository under the Magento Composer root:

git clone git@gitlab.com:mar-pod/magento-ai-toolkit.git packages/magento-ai-toolkit

{
    "repositories": [
        {
            "type": "path",
            "url": "packages/*",
            "options": {
                "symlink": true,
                "versions": {
                    "mar-pod/magento-ai-toolkit": "1.1.1"
                }
            }
        }
    ]
}

Keep the normal package requirement compatible with the mapped development version:

{
    "require": {
        "mar-pod/magento-ai-toolkit": "^1.1"
    }
}

Then run:

composer update mar-pod/magento-ai-toolkit

The installed package under vendor/mar-pod/magento-ai-toolkit will be a symlink to packages/magento-ai-toolkit.

Verification and tests

Validate package metadata:

composer validate --strict

Run the plugin unit tests from a standalone clone after installing development dependencies:

composer install
vendor/bin/phpunit tests/Unit/Installer/ProjectInstallerTest.php

In a Magento project using the local path repository:

vendor/bin/phpunit \
    packages/magento-ai-toolkit/tests/Unit/Installer/ProjectInstallerTest.php

Verify the installed package and generated files:

composer show mar-pod/magento-ai-toolkit
find .agents -maxdepth 4 -type f -print

Troubleshooting

Composer blocks the plugin

Allow it explicitly and repeat the package update:

composer config allow-plugins.mar-pod/magento-ai-toolkit true
composer update mar-pod/magento-ai-toolkit

Rules or skills are missing

Confirm the package is installed, the Magento root is writable, and Composer is running from the correct project:

composer show mar-pod/magento-ai-toolkit
composer dump-autoload

Existing AGENTS.md content

The plugin appends its managed block and does not replace existing instructions. If the managed block already exists, it is not added a second time.

Composer repository failures

Authentication errors for repo.magento.com are unrelated to this plugin. Configure valid Magento Marketplace credentials in the consuming project's auth.json. Never commit auth.json or expose its credentials in logs or documentation.

Uninstallation

Run from the Magento Composer root:

composer remove mar-pod/magento-ai-toolkit

The uninstall hook removes the toolkit-managed block from AGENTS.md and removes only the rules and skills supplied by the package. Unrelated .agents/ content is preserved. If the plugin originally created an otherwise empty AGENTS.md, that file is removed.

Limitations

The plugin installs static Markdown instructions and skill metadata; it does not configure a specific AI client.
Skill discovery depends on support in the AI tool reading the Magento project.
Project-specific AGENTS.md instructions may extend or override toolkit defaults.
The plugin does not install Magento modules, change database schema, clear caches, run indexers, or modify deployment configuration.

Author

Marceli Podstawski — marceli.podstawski@gmail.com

License

Proprietary. See the package metadata and repository terms before redistribution.

mar-pod / magento-ai-toolkit

Maintainers

Package info

Statistics

Security