Plugin Anatomy

A plugin is a directory with a .claude-plugin/plugin.json manifest and a skills/ directory containing skill definitions. Athena discovers and loads plugins from the paths listed in config or passed via --plugin.

Directory Structure

my-plugin/
  .claude-plugin/
    plugin.json          # required — manifest
  skills/
    add-tests/
      SKILL.md           # skill definition with frontmatter
    analyze/
      SKILL.md
  .mcp.json              # optional — MCP server config
  workflow.json          # optional — auto-discovered workflow

The Manifest: `.claude-plugin/plugin.json`

{
  "name": "e2e-test-builder",
  "description": "Iterative workflow runner for adding Playwright E2E tests.",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Manifest Fields

Field	Type	Required	Description
`name`	string	Yes	Unique plugin identifier
`description`	string	Yes	Human-readable description
`version`	string	Yes	Semver version string
`author`	object	No	Author info with `name` field
`repository`	string	No	Source repository URL

Skills: `skills/<name>/SKILL.md`

Each subdirectory inside skills/ that contains a SKILL.md file is a skill. The SKILL.md uses YAML frontmatter to declare the skill's identity and behavior, followed by the prompt body.

---
name: add-e2e-tests
description: Full pipeline orchestrator for adding Playwright E2E tests
user-invocable: true
argument-hint: "<url> <feature>"
allowed-tools:
  - Read
  - Bash
  - Write
---
 
You are an expert test engineer. Your task is to add Playwright E2E tests
for the feature described below.
 
URL: $ARGUMENTS
 
Begin by analyzing the codebase for existing test patterns...

Frontmatter Fields

Field	Type	Description
`name`	string	Required. The slash command name (e.g., `add-e2e-tests` → `/add-e2e-tests`)
`description`	string	Required. Shown in help output and command suggestions
`user-invocable`	boolean	If `true`, appears as a user-facing slash command. Default: `false`
`argument-hint`	string	Argument description shown in help (e.g., `"<url> <feature>"`)
`allowed-tools`	string[]	Optional list of Claude Code tools this skill is permitted to use

Prompt Body

The body below the closing --- is the prompt template sent to Claude when the skill is invoked. Use $ARGUMENTS anywhere in the body to interpolate the user's input.

Skills without user-invocable: true are loaded but not surfaced as commands — they can be used as internal building blocks for other skills or workflows.

Optional: `.mcp.json`

If the plugin provides an MCP server, include a .mcp.json file in the plugin root:

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

Athena merges all plugin .mcp.json files into a single temp config and passes it to the spawned Claude process. MCP server names must be unique across all loaded plugins — a name collision causes a startup error.

When a plugin provides an MCP server, skills in that plugin run with the MCP server's tools available to Claude.

Optional: `workflow.json`

If the plugin directory contains a workflow.json at its root, Athena auto-discovers it as a workflow when the plugin is loaded. If exactly one workflow is discovered across all loaded plugins and no --workflow flag is set, it activates automatically.