Writing Your First Plugin

This guide walks you through creating a plugin that adds a custom skill to Claude Code via Athena.

1. Create the Plugin Directory

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

2. Write the Manifest

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

3. Define a Skill

Create a SKILL.md inside the skill's subdirectory. The YAML frontmatter declares the skill; everything after the closing --- is the prompt body sent to Claude when the skill is invoked.

<!-- 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 (check package-lock.json or yarn.lock)
- Unused dependencies
 
Output a structured report grouped by severity.

The user-invocable: true field makes the skill appear as the /analyze-deps command. The $ARGUMENTS placeholder is replaced with whatever the user types after the command name.

4. Load the Plugin

Point Athena at the plugin directory via the --plugin flag:

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

Or add it to your project config at .athena/config.json:

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

5. Using the Skill

Once the plugin is loaded, /analyze-deps is available in the input bar. Type it to invoke the skill:

/analyze-deps ./src

The argument (./src) replaces $ARGUMENTS in the prompt body before it is sent to Claude.

6. Adding an MCP Server (Optional)

If your plugin needs to expose custom tools to Claude Code, add a .mcp.json file alongside .claude-plugin/:

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

Athena automatically picks this up and includes it in the MCP config passed to Claude Code. Skills in this plugin will then have access to my-tools's custom tools.

7. Publishing to a Marketplace

To share the plugin with your team, add it to a marketplace repository. See Loading & Publishing for the marketplace structure and how to add your plugin to it.

Tips

• Keep each skill focused on one task. The name and argument-hint should make it obvious what the skill does and what input it expects.
• Test skills interactively by loading the plugin locally with --plugin before publishing.
• Skills without user-invocable: true are still loaded — useful for skills that workflows invoke programmatically rather than users invoking directly.