Writing a Plugin

1. Create the Directory

mkdir my-plugin && cd my-plugin
mkdir -p .claude-plugin skills/analyze-deps

2. Write the Manifest

// .claude-plugin/plugin.json
{
  "name": "my-plugin",
  "description": "Custom dependency analysis skill.",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

3. Define a Skill

<!-- skills/analyze-deps/SKILL.md -->
---
name: analyze-deps
description: Analyze project dependencies for outdated packages and vulnerabilities
user-invocable: true
argument-hint: "[path]"
allowed-tools:
  - Read
  - Bash
---
 
Analyze the dependencies of this project.
 
Target path: $ARGUMENTS
 
Identify:
- Outdated packages with available updates
- Packages with known vulnerabilities
- Unused dependencies
 
Output a structured report grouped by severity.

$ARGUMENTS is replaced with whatever the user types after the command name.

4. Load the Plugin

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

Or add to .athena/config.json:

{
  "plugins": ["./my-plugin"]
}

5. Test the Skill

/analyze-deps ./src

6. Add an MCP Server (Optional)

Create .mcp.json alongside .claude-plugin/:

{
  "mcpServers": {
    "my-tools": {
      "command": "node",
      "args": ["./server/index.js"]
    }
  }
}

Skills in this plugin get access to my-tools's custom tools.

7. Publish to a Marketplace

Place your plugin in a marketplace repo 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 it does" }
  ]
}

Once committed, reference it as:

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

Loading Plugins

Plugins resolve from multiple sources, merged and deduplicated:

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

Entries can be relative/absolute paths or marketplace refs (name@owner/repo).

Tips

  • Keep each skill focused on one task
  • Test locally with --plugin before publishing
  • Skills without user-invocable: true are loaded but not surfaced as commands — useful for workflow-invoked skills