SpyBara
Go Premium

plugins.md 2025-12-19 21:01 UTC to 2025-12-20 00:04 UTC

245 added, 290 removed.

2025
Sat 27 06:02 Tue 23 18:02 Sat 20 00:04 Fri 19 21:01 Thu 18 21:01 Wed 17 15:02 Tue 16 21:01 Mon 15 21:01 Sat 13 06:02 Fri 12 21:01 Thu 11 21:02 Wed 10 09:03 Tue 9 18:01 Mon 8 21:01 Sat 6 18:02 Fri 5 00:04 Thu 4 21:02 Wed 3 00:04 Tue 2 21:01 Mon 1 03:31

Create plugins

Create custom plugins to extend Claude Code with slash commands, agents, hooks, Skills, and MCP servers.

Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams. This guide covers creating your own plugins with slash commands, agents, Skills, hooks, and MCP servers.

Looking to install existing plugins? See Discover and install plugins. For complete technical specifications, see Plugins reference.

When to use plugins vs standalone configuration

Claude Code supports two ways to add custom slash commands, agents, and hooks:

Approach Slash command names Best for
Standalone (.claude/ directory) /hello Personal workflows, project-specific customizations, quick experiments
Plugins (directories with .claude-plugin/plugin.json) /plugin-name:hello Sharing with teammates, distributing to community, versioned releases, reusable across projects

Use standalone configuration when:

  • You're customizing Claude Code for a single project
  • The configuration is personal and doesn't need to be shared
  • You're experimenting with slash commands or hooks before packaging them
  • You want short slash command names like /hello or /review

Use plugins when:

  • You want to share functionality with your team or community
  • You need the same slash commands/agents across multiple projects
  • You want version control and easy updates for your extensions
  • You're distributing through a marketplace
  • You're okay with namespaced slash commands like /my-plugin:hello (namespacing prevents conflicts between plugins)

Quickstart

This quickstart walks you through creating a plugin with a custom slash command. You'll create a manifest (the configuration file that defines your plugin), add a slash command, and test it locally using the --plugin-dir flag.

Prerequisites

Create your first plugin

1

Create the plugin directory

Every plugin lives in its own directory containing a manifest and your custom commands, agents, or hooks. Create one now:

mkdir my-first-plugin
2

Create the plugin manifest

The manifest file at .claude-plugin/plugin.json defines your plugin's identity: its name, description, and version. Claude Code uses this metadata to display your plugin in the plugin manager.

Create the .claude-plugin directory inside your plugin folder:

mkdir my-first-plugin/.claude-plugin

Then create my-first-plugin/.claude-plugin/plugin.json with this content:

{
"name": "my-first-plugin",
"description": "A greeting plugin to learn the basics",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}
Field Purpose
name Unique identifier and slash command namespace. Slash commands are prefixed with this (e.g., /my-first-plugin:hello).
description Shown in the plugin manager when browsing or installing plugins.
version Track releases using semantic versioning.
author Optional. Helpful for attribution.

For additional fields like homepage, repository, and license, see the full manifest schema.

3

Add a slash command

Slash commands are Markdown files in the commands/ directory. The filename becomes the slash command name, prefixed with the plugin's namespace (hello.md in a plugin named my-first-plugin creates /my-first-plugin:hello). The Markdown content tells Claude how to respond when someone runs the slash command.

Create a commands directory in your plugin folder:

mkdir my-first-plugin/commands

Then create my-first-plugin/commands/hello.md with this content:

---
description: Greet the user with a friendly message
---

# Hello Command

Greet the user warmly and ask how you can help them today.
4

Test your plugin

Run Claude Code with the --plugin-dir flag to load your plugin:

claude --plugin-dir ./my-first-plugin

Once Claude Code starts, try your new command:

/my-first-plugin:hello

You'll see Claude respond with a greeting. Run /help to see your command listed under the plugin namespace.

5

Add slash command arguments

Make your slash command dynamic by accepting user input. The $ARGUMENTS placeholder captures any text the user provides after the slash command.

Update your hello.md file:

---
description: Greet the user with a personalized message
---

# Hello Command

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

Restart Claude Code to pick up the changes, then try the command with your name:

/my-first-plugin:hello Alex

Claude will greet you by name. For more argument options like $1, $2 for individual parameters, see Slash commands.

You've successfully created and tested a plugin with these key components:

  • Plugin manifest (.claude-plugin/plugin.json): describes your plugin's metadata
  • Commands directory (commands/): contains your custom slash commands
  • Command arguments ($ARGUMENTS): captures user input for dynamic behavior

Plugin structure overview

You've created a plugin with a slash command, but plugins can include much more: custom agents, Skills, hooks, MCP servers, and LSP servers.

Directory Location Purpose
.claude-plugin/ Plugin root Contains only plugin.json manifest (required)
commands/ Plugin root Slash commands as Markdown files
agents/ Plugin root Custom agent definitions
skills/ Plugin root Agent Skills with SKILL.md files
hooks/ Plugin root Event handlers in hooks.json
.mcp.json Plugin root MCP server configurations
.lsp.json Plugin root LSP server configurations for code intelligence

Develop more complex plugins

Once you're comfortable with basic plugins, you can create more sophisticated extensions.

Add Skills to your plugin

Plugins can include Agent Skills to extend Claude's capabilities. Skills are model-invoked; Claude autonomously uses them based on the task context.

To add Skills to your plugin, create a skills/ directory at your plugin root and add Skill folders with SKILL.md files. Plugin Skills are automatically available when the plugin is installed.

For complete Skill authoring guidance, see Agent Skills.

Add LSP servers to your plugin

LSP (Language Server Protocol) plugins give Claude real-time code intelligence. If you need to support a language that doesn't have an official LSP plugin, you can create your own by adding an .lsp.json file to your plugin:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Users installing your plugin must have the language server binary installed on their machine.

For complete LSP configuration options, see LSP servers.

Organize complex plugins

For plugins with many components, organize your directory structure by functionality. For complete directory layouts and organization patterns, see Plugin directory structure.

Test your plugins locally

Use the --plugin-dir flag to test plugins during development. This loads your plugin directly without requiring installation.

claude --plugin-dir ./my-plugin

As you make changes to your plugin, restart Claude Code to pick up the updates. Test your plugin components:

  • Try your commands with /command-name
  • Check that agents appear in /agents
  • Verify hooks work as expected

Debug plugin issues

If your plugin isn't working as expected:

  1. Check the structure: Ensure your directories are at the plugin root, not inside .claude-plugin/
  2. Test components individually: Check each command, agent, and hook separately
  3. Use validation and debugging tools: See Debugging and development tools for CLI commands and troubleshooting techniques

Share your plugins

When your plugin is ready to share:

  1. Add documentation: Include a README.md with installation and usage instructions
  2. Version your plugin: Use semantic versioning in your plugin.json
  3. Create or use a marketplace: Distribute through plugin marketplaces for installation
  4. Test with others: Have team members test the plugin before wider distribution

Once your plugin is in a marketplace, others can install it using the instructions in Discover and install plugins.

Convert existing configurations to plugins

If you already have custom commands, Skills, or hooks in your .claude/ directory, you can convert them into a plugin for easier sharing and distribution.

Migration steps

1

Create the plugin structure

Create a new plugin directory:

mkdir -p my-plugin/.claude-plugin

Create the manifest file at my-plugin/.claude-plugin/plugin.json:

{
"name": "my-plugin",
"description": "Migrated from standalone configuration",
"version": "1.0.0"
}
2

Copy your existing files

Copy your existing configurations to the plugin directory:

# Copy commands
cp -r .claude/commands my-plugin/

# Copy agents (if any)
cp -r .claude/agents my-plugin/

# Copy skills (if any)
cp -r .claude/skills my-plugin/
3

Migrate hooks

If you have hooks in your settings, create a hooks directory:

mkdir my-plugin/hooks

Create my-plugin/hooks/hooks.json with your hooks configuration. Copy the hooks object from your .claude/settings.json or settings.local.json—the format is the same:

{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{ "type": "command", "command": "npm run lint:fix $FILE" }]
}
]
}
}
4

Test your migrated plugin

Load your plugin to verify everything works:

claude --plugin-dir ./my-plugin

Test each component: run your commands, check agents appear in /agents, and verify hooks trigger correctly.

What changes when migrating

Standalone (.claude/) Plugin
Only available in one project Can be shared via marketplaces
Files in .claude/commands/ Files in plugin-name/commands/
Hooks in settings.json Hooks in hooks/hooks.json
Must manually copy to share Install with /plugin install

Next steps

Now that you understand Claude Code's plugin system, here are suggested paths for different goals:

For plugin users

For plugin developers

To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt