Skip to main content
Claude Code plugins extend functionality through custom commands, agents, skills, and hooks. This guide will walk you through creating your first plugin.

​
Prerequisites

Before you begin:
  • Claude Code installed and working
  • Basic understanding of markdown and YAML
  • Text editor of your choice
  • (Optional) Git for version control

​
Quick Start

The fastest way to create a plugin is using the plugin-dev toolkit: 
/plugin install plugin-dev
/plugin-dev:create-plugin My first plugin
This launches a guided workflow that helps you through the entire process.

​
Manual Plugin Creation

To understand plugin structure, let’s create a simple plugin manually.

​
Step 1: Create Plugin Directory

Create a directory for your plugin: 
mkdir my-first-plugin
cd my-first-plugin

​
Step 2: Create Plugin Manifest

Every plugin needs a manifest at .claude-plugin/plugin.json: 
mkdir .claude-plugin
Create .claude-plugin/plugin.json: 
{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "My first Claude Code plugin",
  "author": {
    "name": "Your Name",
    "email": "[email protected]"
  }
}
The name field must be unique and use kebab-case (lowercase with hyphens).

​
Step 3: Add a Command

Create a simple slash command in commands/hello.md: 
mkdir commands
Create commands/hello.md: 
---
description: Say hello to the user
argument-hint: [name]
---

Greet the user warmly.

If $ARGUMENTS is provided, use that as the name.
Otherwise, just say "Hello!"

Be friendly and welcoming.

​
Step 4: Test Your Plugin

Load your plugin locally: 
cc --plugin-dir /path/to/my-first-plugin
Then try your command: 
/hello World
Claude should greet you!

​
Plugin Structure

Your plugin now has this structure: 
my-first-plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata (required)
└── commands/
    └── hello.md              # Your slash command
You can add more components: 
my-first-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required
├── commands/                # Slash commands (optional)
│   └── hello.md
├── agents/                  # Specialized agents (optional)
│   └── helper.md
├── skills/                  # Auto-activating skills (optional)
│   └── my-skill/
│       └── SKILL.md
├── hooks/                   # Event handlers (optional)
│   ├── hooks.json
│   └── scripts/
├── .mcp.json                # MCP servers (optional)
└── README.md                # Documentation (recommended)

​
Next Steps

1

Add an Agent

Create a specialized agent in agents/See Agent Development
2

Add a Skill

Create auto-activating expertise in skills/See Skill Development
3

Add Hooks

Create event handlers in hooks/See Hook Development
4

Write Documentation

Create a comprehensive README.mdSee Plugin Structure

​
Development Workflow

​
1. Develop Locally

Use --plugin-dir to test changes: 
cc --plugin-dir /path/to/my-plugin
Changes take effect immediately in new sessions.

​
2. Add to Project

Once working, add to your project’s .claude/settings.json: 
{
  "plugins": [
    "file:///absolute/path/to/my-plugin"
  ]
}

​
3. Publish

When ready to share:
  1. Push to GitHub
  2. Create a release with version tag
  3. Submit to plugin marketplace
See Publishing Guide for details.

​
Common Patterns

​
Simple Command Plugin

Just commands, no agents or hooks: 
command-plugin/
├── .claude-plugin/
│   └── plugin.json
└── commands/
    ├── command1.md
    └── command2.md

​
Agent-Focused Plugin

Primarily provides specialized agents: 
agent-plugin/
├── .claude-plugin/
│   └── plugin.json
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

​
Skill Plugin

Provides auto-activating expertise: 
skill-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── my-skill/
        ├── SKILL.md
        ├── examples/
        └── references/
Uses all component types: 
full-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── agents/
├── skills/
├── hooks/
├── .mcp.json
└── README.md

​
Best Practices

Start Simple

Begin with just a command or agent, add complexity as needed

Use ${CLAUDE_PLUGIN_ROOT}

Always use this variable for portable path references

Test Thoroughly

Test on different operating systems and projects

Document Well

Clear README with examples and usage instructions

​
Debugging Tips

​
Enable Debug Mode

claude --debug
This shows:
  • Plugin loading process
  • Component discovery
  • Hook execution
  • Agent triggering

​
Check Plugin Loaded

Ask Claude: 
"What plugins are currently loaded?"

​
Verify Component Discovery

"What commands are available from my-first-plugin?"
"What agents are available from my-first-plugin?"

​
Common Issues

Plugin not loading:
  • Check plugin.json syntax
  • Verify directory structure
  • Ensure .claude-plugin directory exists
Command not found:
  • Check file is in commands/ directory
  • Verify .md extension
  • Check YAML frontmatter syntax
Agent not triggering:
  • Review description field for trigger phrases
  • Add <example> blocks to description
  • Make description more specific

​
Resources

Plugin Structure

Detailed guide to plugin organization

Commands

Creating slash commands

Agents

Building specialized agents

Skills

Auto-activating expertise

Hooks

Event-driven automation

MCP Integration

Connecting external tools

​
Examples

Study these bundled plugins for examples:
  • commit-commands: Simple command-based plugin
  • hookify: Hooks and configuration files
  • feature-dev: Commands, agents, and workflow
  • plugin-dev: Skills, agents, and comprehensive toolkit

​
Get Help

For more guidance: 
/plugin install plugin-dev
/plugin-dev:create-plugin
The plugin-dev toolkit provides:
  • 7 expert skills covering all aspects
  • Guided creation workflow
  • Validation and testing utilities
  • Working examples and templates

Build docs developers (and LLMs) love

Get started for freeTalk to us