Loading & Publishing

Loading & Publishing

Loading Plugins

Athena loads plugins from directory paths or marketplace refs. There is no separate plugin manager — Athena resolves everything itself using git and the filesystem.

Via CLI Flag

Pass a path to a plugin directory:

athena-flow --plugin=./my-plugin
athena-flow --plugin=/shared/team-tools --plugin=./local-extras

Repeatable. All --plugin dirs are merged with plugins from config files.

Via Config File

Add plugin references to ~/.config/athena/config.json (global) or .athena/config.json (project):

{
  "plugins": [
    "./plugins/local-plugin",
    "e2e-test-builder@lespaceman/athena-workflow-marketplace"
  ]
}

Entries are either relative/absolute directory paths or marketplace refs in name@owner/repo format.

Marketplace Refs

A marketplace ref like e2e-test-builder@lespaceman/athena-workflow-marketplace causes Athena to:

  1. Clone the repo lespaceman/athena-workflow-marketplace into ~/.config/athena/marketplaces/lespaceman/athena-workflow-marketplace/ (first use only)
  2. Pull the latest on subsequent startups (graceful degradation if offline — uses cached version)
  3. Read .claude-plugin/marketplace.json to find the e2e-test-builder entry
  4. Resolve the plugin from the source path within the cached repo

Plugin Load Order

Plugins are merged and deduplicated in this order:

  1. Workflow's plugins[] (if a workflow is active)
  2. Global config plugins[]
  3. Project config plugins[]
  4. --plugin CLI flags

Publishing a Plugin

1. Build the Plugin Directory

Follow the Plugin Anatomy guide. At minimum you need:

my-plugin/
  .claude-plugin/plugin.json
  skills/<skill-name>/SKILL.md

2. Test Locally

Load the plugin directly with --plugin and verify skills appear and work:

athena-flow --plugin=./my-plugin

Type /help in the input bar to confirm the skill is listed.

3. Add to a Marketplace Repo

In a marketplace repository, place your plugin at plugins/my-plugin/ and register it in .claude-plugin/marketplace.json:

{
  "name": "my-marketplace",
  "owner": {"name": "Your Name"},
  "metadata": {
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "my-plugin",
      "description": "What this plugin does"
    }
  ]
}

With pluginRoot set to "./plugins", the source field can use short names. Without it, use relative paths: "source": "./plugins/my-plugin".

4. Commit and Push

Once committed, anyone can reference the plugin via marketplace ref:

{
  "plugins": ["my-plugin@your-org/your-marketplace-repo"]
}

Hosting a Private Marketplace

Any GitHub repository with the correct structure acts as a marketplace. Minimum structure for plugins:

your-marketplace/
  .claude-plugin/
    marketplace.json     # plugin catalog
  plugins/
    my-plugin/
      .claude-plugin/
        plugin.json
      skills/
        my-skill/
          SKILL.md

To also host workflows, add:

  .athena-workflow/
    marketplace.json     # workflow catalog
  .workflows/
    my-workflow/
      workflow.json

Users reference it as plugin-name@your-org/your-marketplace.