Plugin Bundles

Plugin Bundles

A workflow can declare which plugins it depends on in its plugins[] array. When the workflow activates, Athena automatically resolves and loads those plugins — you don't need to pass --plugin flags separately.

Why Workflows Bundle Plugins

The e2e-test-builder workflow needs the e2e-test-builder plugin's skills (/add-e2e-tests, /generate-test-cases, etc.) to function. Declaring the dependency in the workflow makes the relationship explicit and removes the need for users to know which plugins to load manually.

Plugin References in workflow.json

Use marketplace refs or local paths in the plugins[] array:

{
  "name": "e2e-test-builder",
  "plugins": [
    "e2e-test-builder@lespaceman/athena-workflow-marketplace",
    "site-knowledge@lespaceman/athena-workflow-marketplace"
  ],
  "promptTemplate": "..."
}

When this workflow activates, Athena resolves both plugins from the marketplace and loads them exactly as if they had been passed via --plugin.

Plugin Load Order

Workflow plugins are resolved first, then merged with:

  1. Global config plugins[]
  2. Project config plugins[]
  3. --plugin CLI flags

Duplicates are deduplicated — if the same plugin path appears in both the workflow and the config, it is loaded once.

MCP Config Merging

If any of the workflow's plugins include .mcp.json files, their mcpServers entries are merged into the session's MCP config. MCP server names must be unique across all plugins; a collision causes a startup error with a clear message identifying which plugins conflict.

Marketplace Colocation

In the Athena marketplace repo, workflows and their plugin dependencies live in the same repository. This keeps workflow definitions and plugin skill sets in sync:

athena-workflow-marketplace/
  .workflows/
    e2e-test-builder/
      workflow.json            ← references e2e-test-builder plugin
  plugins/
    e2e-test-builder/          ← the plugin it references
      .claude-plugin/
        plugin.json
      skills/
        add-e2e-tests/
          SKILL.md

When contributing a new workflow, you'll usually add or update a plugin in the same PR.

Manual Override

If you want to use a workflow but swap out one of its plugins for a local version, load both explicitly — Athena deduplicates by resolved path, so your local version wins if it resolves to the same plugin name:

athena-flow --workflow=e2e-test-builder --plugin=./my-custom-e2e-plugin

The --plugin flag plugins are loaded last in the merge order, so they take precedence for any skills or MCP servers with name conflicts.