Skip to content
Skills Library
Programming · Building & coding

message-queue

/message-queue

Scaffold a full async message-queue surface on an existing module — communication.xml topic, queue_topology/publisher/consumer.xml bindings, a typed message DTO, a publisher, and an idempotent consumer/handler. Use for 'process X asynchronously' / 'add a queue consumer'. Goes beyond magento2-tools:module-create's queue stub. For a new module use `magento2-tools:module-create` first.

Licence
MIT
Last repository change
04.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
15
Scripts
5
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 04.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 5 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: templates/consumer.php, templates/message-interface.php, templates/message-model.php, templates/publisher.php, templates/test-consumer-unit.php

What it does and when to use it

Scaffold a full async message-queue surface on an existing module — communication.xml topic, queue_topology/publisher/consumer.xml bindings, a typed message DTO, a publisher, and an idempotent consumer/handler. Use for 'process X asynchronously' / 'add a queue consumer'. Goes beyond magento2-tools:module-create's queue stub. For a new module use `magento2-tools:module-create` first.

Triggers from the description

process X asynchronouslyadd a queue consumer
Original author description

Scaffold a full async message-queue surface on an existing module — communication.xml topic, queue_topology/publisher/consumer.xml bindings, a typed message DTO, a publisher, and an idempotent consumer/handler. Use for 'process X asynchronously' / 'add a queue consumer'. Goes beyond magento2-tools:module-create's queue stub. For a new module use `magento2-tools:module-create` first.

How it works

  1. Core Rules
  2. Workflow
  3. Inputs
  4. Outputs
  5. Reference Files
  6. Templates
  7. Acceptance Criteria
  8. Related Skills
Original SKILL.md headings · 263 lines, 1,533 words
SKILL.md preview
---
name: message-queue
version: 1.1.3
description:
    Scaffold a full async message-queue surface on an existing module — communication.xml
    topic, queue_topology/publisher/consumer.xml bindings, a typed message DTO, a publisher,
    and an idempotent consumer/handler. Use for 'process X asynchronously' / 'add a queue
    consumer'. Goes beyond magento2-tools:module-create's queue stub. For a new module use
    `magento2-tools:module-create` first.
---

# Magento 2 Message Queue

Scaffold a full **async message-queue** surface onto an **existing** Magento 2 module: a
`communication.xml` topic, the `queue_topology.xml` / `queue_publisher.xml` /
`queue_consumer.xml` bindings, a typed message DTO (interface + model + `di.xml`
preference), a `PublisherInterface`-backed publisher, and an idempotent consumer that
decodes the typed message and delegates to a domain handler.

This goes beyond the bare queue stub `module-create` emits: it wires all five
XML config files so the topic ↔ topology ↔ publisher ↔ consumer ↔ queue chain actually
resolves, and bakes in idempotency + poison-message handling. For a brand-new module run
`module-create` first.

## Core Rules

- **Topic name convention:** `{vendor_lower}.{module_lower}.{entity}.{action}` (all
  lowercase, dot-separated). The SAME topic string is the join key across
  `communication.xml`, `queue_topology.xml`, `queue_publisher.xml`, and the publisher's
  `TOPIC` constant — drift across these files is the #1 message-queue bug. See
  `context/references/naming.md` §9 Queue.
- **Default `connection="db"`.** Use the MySQL-backed queue (`db`) unless the project has
  a confirmed, running AMQP/RabbitMQ broker. Only set `connection="amqp"` when AMQP is
  confirmed; `db` requires no broker and is the safe default.
- **Messages are typed DTOs, never arrays.** The message payload is a typed interface
  (`Api/Data/{EntityName}Interface`) + implementation (`Model/{EntityName}`) bound by a
  `di.xml` `<preference>`. `communication.xml` declares the topic `request` as the
  interface FQCN so the framework (de)serializes it. NEVER publish a bare array — it
  defeats schema validation and breaks the consumer's typed signature.
- **Consumers must be idempotent.** A redelivered message (broker retry, crash between
  ack and commit) must produce the same end state — a second delivery of the same message
  is a safe no-op. Guard with a processed-marker / status flag in the handler.
- **Handle poison messages.** A message that can never succeed must be rejected (not
  re-queued forever). Catch the un-retryable case, log it, and let it drop / route to a
  dead-letter queue — see `${CLAUDE_SKILL_DIR}/references/pitfalls.md`.
- **Never hardcode an infinite loop.** Document `--max-messages` and `max_idle_time`
  guidance for `queue:consumers:start`; rely on the `consumers_runner` cron rather than a
  hand-rolled `while (true)`. See `${CLAUDE_SKILL_DIR}/references/consumer-runtime.md`.
- **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` (or run
`${CLAUDE_PLUGIN_ROOT}/skills/context/scripts/resolve-context.sh`); capture the
JSON as `{ctx}`. Abort if `{ctx.magento_root}` is unresolved.

**Hard stop if the target module does not exist.** Offer `module-create` and do
not scaffold a queue surface into a non-existent module.

### Phase 1 — Resolve Inputs

Ask for any missing values in one batch.

| Input | Default | Notes |
|-------|---------|-------|
| Module | (ask) | Existing `{Vendor}_{Module}` |
| Topic name | (ask) | `{vendor_lower}.{module_lower}.{entity}.{action}`, e.g. `acme.orders.order.export` |
| Message DTO | (ask) | `{EntityName}` (PascalCase) + its typed fields (name + type each) |
| Publisher class name | (ask) | PascalCase, e.g. `OrderExportPublisher`; placed in `Model/` |
| Consumer name | (ask) | PascalCase, e.g. `OrderExportConsumer`; placed in `Model/Consumer/`; also the `consumer.xml` `name` |
| Handler method | (ask) | The domain service method the consumer delegates to (e.g. `process`) |
| Connection | `db` | `db` (MySQL, no broker) or `amqp` (confirmed RabbitMQ only) |
| Queue name | (ask) | `{vendor_lower}.{module_lower}.{queue}`, e.g. `acme.orders.export` |
| Exchange name | `magento` (db) / (ask, AMQP) | AMQP only; `db` connection uses the implicit `magento` exchange |

See `${CLAUDE_SKILL_DIR}/references/mq-architecture.md` and
`${CLAUDE_SKILL_DIR}/references/message-dto.md`.

### Phase 2 — Plan

Present every file to create or modify. Typical file set:

- `etc/communication.xml` (merge — topic declaration)
- `etc/queue_topology.xml` (merge — exchange + binding)
- `etc/queue_publisher.xml` (merge — publisher → connection/exchange)
- `etc/queue_consumer.xml` (merge — consumer → queue/handler)
- `etc/di.xml` (merge — DTO `<preference>`)
- `Api/Data/{EntityName}Interface.php`
- `Model/{EntityName}.php`
- `Model/{PublisherName}.php`
- `Model/Consumer/{ConsumerName}.php`
- `Test/Unit/Model/Consumer/{ConsumerName}Test.php`

Wait for "proceed."

### Phase 3 — Test First, then Generate

**3A — Write the failing test (RED).** Before generating implementation code, write the
consumer unit test and confirm it fails for the right reason (class-not-found, not a setup
error):

- **Consumer test** (`Test/Unit/Model/Consumer/{ConsumerName}Test.php`): mock the typed
  `{EntityName}Interface` message and the injected domain handler/service. Assert
  `process($message)` calls the handler `expects(self::once())` with the decoded message.
  Then assert that a **second** delivery of the **same** message is a safe no-op for the
  consumer class itself (idempotency-safety). Mock expectations ARE assertions — no
  `markTestIncomplete`, no `self::assertTrue(true)`.
- **Prerequisite:** the injected domain handler/service (e.g. `{EntityName}Handler`) must
  already exist or be stubbed before running the RED test, otherwise the failure is a
  handler-not-found error rather than the intended consumer-not-found RED.

Follow `context/references/tdd-discipline.md`.

**3B — Generate implementation (GREEN).** Write the minimal code to make the 3A test
pass, using the templates:

- `${CLAUDE_SKILL_DIR}/templates/communication.xml`
- `${CLAUDE_SKILL_DIR}/templates/queue_topology.xml`
- `${CLAUDE_SKILL_DIR}/templates/queue_publisher.xml`
- `${CLAUDE_SKILL_DIR}/templates/queue_consumer.xml`
- `${CLAUDE_SKILL_DIR}/templates/queue-di.xml`
- `${CLAUDE_SKILL_DIR}/templates/message-interface.php`
- `${CLAUDE_SKILL_DIR}/templates/message-model.php`
- `${CLAUDE_SKILL_DIR}/templates/publisher.php`
- `${CLAUDE_SKILL_DIR}/templates/consumer.php`
- `${CLAUDE_SKILL_DIR}/templates/test-consumer-unit.php`

The SAME topic string must appear in `communication.xml`, `queue_topology.xml`,
`queue_publisher.xml`, and the publisher's `TOPIC` const; the SAME queue name in
`queue_topology.xml` + `queue_consumer.xml`; the SAME consumer name in
`queue_consumer.xml` + the consumer class + its test. See
`${CLAUDE_SKILL_DIR}/references/mq-architecture.md` and
`${CLAUDE_SKILL_DIR}/references/pitfalls.md`.

### Phase 4 — Verify

- `php -l` on every generated `.php` file.
- `xmllint --noout` on every generated `.xml` file.
- Run the Phase 3A test with `{ctx.runner} vendor/bin/phpunit` and confirm it now
  **passes** (it failed before 3B); run the module suite to confirm nothing else broke.
- Run `review --diff` (gate: zero Critical/High findings).
- **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`.
- Consult `${CLAUDE_SKILL_DIR}/references/pitfalls.md` before declaring Phase 4 done —
  verify the topic/queue/consumer names are byte-identical across all wiring points.

### Phase 5 — Report

Write a brief Markdown report to
`{output_root}/message-queues/{Vendor}_{Module}-{topic}-{date}.md` listing:

- Topic name, queue name, consumer name, connection
- Files generated
- Test path + red→green evidence
- `bin/magento setup:upgrade` + `bin/magento cache:flush` commands
- How to run the consumer: `bin/magento queue:consumers:start {ConsumerName} --max-messages=1000`
- How to verify wiring: `bin/magento queue:consumers:list`

`{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>/message-queues/`; otherwise default to
`{ctx.docs_root}/message-queues/`. `feature` passes this so a feature
run's reports collect under its folder.

> **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

```
/message-queue --module=Acme_Orders --topic=acme.orders.order.export \
  --entity=OrderExport --publisher=OrderExportPublisher --consumer=OrderExportConsumer \
  --queue=acme.orders.export --connection=db [--docs-root=<path>]
```

## Outputs

```
{ctx.magento_root}/app/code/{Vendor}/{Module}/etc/communication.xml             # merge
{ctx.magento_root}/app/code/{Vendor}/{Module}/etc/queue_topology.xml            # merge
{ctx.magento_root}/app/code/{Vendor}/{Module}/etc/queue_publisher.xml           # merge
{ctx.magento_root}/app/code/{Vendor}/{Module}/etc/queue_consumer.xml            # merge
{ctx.magento_root}/app/code/{Vendor}/{Module}/etc/di.xml                        # merge
{ctx.magento_root}/app/code/{Vendor}/{Module}/Api/Data/{EntityName}Interface.php
{ctx.magento_root}/app/code/{Vendor}/{Module}/Model/{EntityName}.php
{ctx.magento_root}/app/code/{Vendor}/{Module}/Model/{PublisherName}.php
{ctx.magento_root}/app/code/{Vendor}/{Module}/Model/Consumer/{ConsumerName}.php
{ctx.magento_root}/app/code/{Vendor}/{Module}/Test/Unit/Model/Consumer/{ConsumerName}Test.php

{output_root}/message-queues/{Vendor}_{Module}-{topic}-{date}.md
```

## Reference Files

- `${CLAUDE_SKILL_DIR}/references/mq-architecture.md` — how the topic ↔ topology
  exchange/binding ↔ publisher ↔ consumer ↔ queue fit together; `db` vs `amqp`.
- `${CLAUDE_SKILL_DIR}/references/message-dto.md` — the typed message DTO (interface +
  impl + `di.xml` preference), serialization, why not arrays.
- `${CLAUDE_SKILL_DIR}/references/consumer-runtime.md` — `queue:consumers:start`,
  `queue:consumers:list`, the `consumers_runner` cron, `--max-messages`, `max_idle_time`.
- `${CLAUDE_SKILL_DIR}/references/pitfalls.md` — idempotency, poison messages / DLQ, no
  heavy synchronous work, serialization mismatch, topic/queue name drift across the XML.
- `context/references/naming.md` — topic/queue/consumer naming conventions.
- `context/references/tdd-discipline.md` — shared test-first RED/GREEN loop.
- `context/references/php-coding-style.md` — PER-CS + Magento coding style.
- `context/references/placeholder-schema.md` — token registry.
- `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/communication.xml` → `etc/communication.xml` (merge)
- `templates/queue_topology.xml` → `etc/queue_topology.xml` (merge)
- `templates/queue_publisher.xml` → `etc/queue_publisher.xml` (merge)
- `templates/queue_consumer.xml` → `etc/queue_consumer.xml` (merge)
- `templates/queue-di.xml` → `etc/di.xml` (merge)
- `templates/message-interface.php` → `Api/Data/{EntityName}Interface.php`
- `templates/message-model.php` → `Model/{EntityName}.php`
- `templates/publisher.php` → `Model/{PublisherName}.php`
- `templates/consumer.php` → `Model/Consumer/{ConsumerName}.php`
- `templates/test-consumer-unit.php` → `Test/Unit/Model/Consumer/{ConsumerName}Test.php`

All templates follow the placeholder registry in
`context/references/placeholder-schema.md`. Every token used must be in the
Registry there — `tests/test-placeholder-tokens.sh` enforces it.

## Acceptance Criteria

- All generated files pass `php -l` / `xmllint --noout`.
- Topic name follows `{vendor_lower}.{module_lower}.{entity}.{action}`; the SAME topic
  string appears in `communication.xml`, `queue_topology.xml`, `queue_publisher.xml`, and
  the publisher's `TOPIC` const.
- The same queue name appears in `queue_topology.xml` + `queue_consumer.xml`; the same
  consumer name in `queue_consumer.xml` + the consumer class + its test.
- `connection="db"` unless AMQP is confirmed.
- Message payload is a typed DTO (interface + model + `di.xml` preference), never an array.
- Consumer test: handler mock uses `expects(self::once())` with the decoded message; a
  second delivery is a safe no-op; no `markTestIncomplete`, no `self::assertTrue(true)`.
- `review --diff` returns zero Critical/High findings.

## Related Skills

| Phase | Skill |
|-------|-------|
| 0 | `context` |
| Before (if module absent) | `module-create` |
| The bare queue stub | `module-create` |
| After | `review --diff` |
Files in this package (15)
  • SKILL.md 14 KB
  • references/consumer-runtime.md 3 KB
  • references/message-dto.md 3 KB
  • references/mq-architecture.md 5 KB
  • references/pitfalls.md 5 KB
  • templates/communication.xml 1 KB
  • templates/consumer.php 2 KB
  • templates/message-interface.php 1 KB
  • templates/message-model.php 1 KB
  • templates/publisher.php 2 KB
  • templates/queue-di.xml 1 KB
  • templates/queue_consumer.xml 1 KB
  • templates/queue_publisher.xml 1 KB
  • templates/queue_topology.xml 1 KB
  • templates/test-consumer-unit.php 4 KB

Versions

The database has no other skills named message-queue.

Database snapshot: 13.11.2026 · package version 4f491e9b6bb1 (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

  • 100system-config
    Add admin store configuration to an existing module — system.xml section/group/field, config.xml defaults, ACL, optional source/backend models, plus a typed Config reader (ScopeConfigInterface wrapper with store-aware getters). Use for 'add a config field/toggle/API-key setting'…
  • 95backend-message-queue
    Use this skill when the user says 'message queue', 'Kafka', 'RabbitMQ', 'SQS', 'pub-sub', 'event bus', 'consumer group', 'topic', 'queue', 'at-least-once', 'exactly-once', 'idempotent consumer', 'event sourcing', 'dead letter queue', 'DLQ', 'message broker', 'producer',…
  • 100scaffold-message-handler
    Scaffold a message consumer in a .NET workspace (MassTransit, RabbitMQ, Azure Service Bus when detected, or similar). Collects requirements first. Use when creating a consumer or invoking /scaffold-message-handler.
  • 100indexer
    Scaffold a custom Magento 2 indexer + materialized view (mview) on an existing module — `indexer.xml`, `mview.xml` subscriptions, an `ActionInterface` indexer (executeFull/executeList/executeRow) + Mview `ActionInterface` (execute), delegating to a batched action class. Use for…
  • 90magento-di
    Configure Magento 2 dependency injection — di.xml, types, virtual types, preferences, argument replacement, and Object Manager. Use when wiring dependencies, creating class variations, or configuring module integrations.
  • 100scaffold
    Architecture-aware feature scaffolding for .NET 10 projects. Detects the project's architecture (VSA, Clean Architecture, DDD, Modular Monolith) and generates complete feature slices with all required layers: endpoint, handler, validator, DTOs, EF configuration, and integration…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.