Plugin System

Use Claude Code plugin system to create custom commands, agents, and workflows

Plugin System ¶

The Claude Code plugin system allows you to extend Claude's capabilities by creating custom slash commands, specialized agents, reusable skills, and automation hooks. With plugins, you can codify your team's best practices and workflows.

What are Plugins?¶

Core Concepts ¶

A Claude Code plugin is a directory with a specific file structure that can add the following components:

Component	Description	File Format
Commands	Custom slash commands	`.md` files
Agents	Specialized task subagents	`.md` files
Skills	Reusable knowledge and capabilities	Directory + `SKILL.md`
Hooks	Event-triggered automation	`hooks.json`

Why Plugins?¶

Team standardization: Encode coding standards and review criteria as executable commands
Workflow automation: Automate repetitive tasks like commits, deployments, reviews
Knowledge sharing: Share best practices and expertise across team members
Custom experience: Customize Claude's behavior for project needs

Plugin Directory Structure ¶

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: Plugin manifest
├── commands/                 # Slash commands (.md files)
│   ├── review.md
│   └── deploy.md
├── agents/                   # Subagent definitions (.md files)
│   └── code-reviewer.md
├── skills/                   # Agent skills (subdirectories)
│   └── coding-standards/
│       └── SKILL.md
├── hooks/
│   └── hooks.json           # Event handler configuration
├── .mcp.json                # MCP server definitions (optional)
└── scripts/                 # Helper scripts (optional)

Quick Start ¶

Install Plugins ¶

# Install from marketplace
/plugin install plugin-name@claude-code-marketplace

# Install from local directory
claude --plugin-dir /path/to/my-plugin

Use Plugin Creation Wizard ¶

/plugin-dev:create-plugin

This command guides you through 8 phases to create a complete plugin.

Creating Custom Commands ¶

Basic Command Format ¶

Create .md files in the commands/ directory:

---
description: Perform code review
argument-hint: [file-path]
allowed-tools: Read, Bash(git:*)
---

Please review the code quality of: @$1

Focus on:
1. Code readability
2. Potential bugs
3. Performance issues
4. Security vulnerabilities

YAML Frontmatter Configuration ¶

Field	Description	Example
`description`	Command description (shown in /help)	`Perform code review`
`argument-hint`	Parameter hints	`[file-path] [options]`
`allowed-tools`	Permitted tools	`Read, Bash(git:*)`
`model`	Specify model	`opus` or `sonnet`

Using Dynamic Arguments ¶

$1, $2, $3... - Positional arguments
$ARGUMENTS - All arguments
@path/to/file - File reference
!command`` - Execute Bash command

Command Examples ¶

Code Review Command (commands/review.md):

---
description: Comprehensive code review
argument-hint: [file-or-directory]
allowed-tools: Read, Grep, Glob
model: opus
---

Perform a comprehensive code review of @$1.

Checklist:
- [ ] Code style follows project standards
- [ ] No potential security issues
- [ ] Error handling is complete
- [ ] Tests are needed

If it's a directory, first use Glob tool to find all relevant files.

Smart Commit Command (commands/commit.md):

---
description: Smart commit with generated message
allowed-tools: Bash(git:*)
---

1. Run `git status` to see changes
2. Run `git diff --staged` to analyze staged changes
3. Generate a conventional commit message based on changes
4. Execute `git commit`

Commit message format:
- feat: New feature
- fix: Bug fix
- docs: Documentation update
- refactor: Refactoring
- test: Test related

Creating Custom Agents ¶

Agent Definition Format ¶

Create .md files in the agents/ directory:

---
description: Specialized code review agent
model: opus
tools: Read, Grep, Glob
---

You are a professional code review agent. Your task is to:

1. Carefully read the provided code
2. Identify potential issues
3. Provide specific improvement suggestions
4. Focus on security and performance

Always be constructive and specific.

Agent Types ¶

Type	Purpose	Example
Review Agent	Code review, PR review	`code-reviewer`
Test Agent	Generate and run tests	`test-generator`
Doc Agent	Generate documentation	`doc-writer`
Refactor Agent	Code refactoring	`refactorer`

Creating Skills ¶

Skill Directory Structure ¶

skills/
└── coding-standards/
    ├── SKILL.md              # Required: Skill definition
    ├── references/           # Reference materials
    │   └── style-guide.md
    └── examples/             # Example code
        └── good-practices.md

SKILL.md Format ¶

# Coding Standards Skill

## Overview
This skill contains team coding standards and best practices.

## Knowledge Content

### Naming Conventions
- Variables: camelCase
- Constants: UPPER_SNAKE_CASE
- Classes: PascalCase
- Files: kebab-case

### Code Style
- Use 2-space indentation
- Max line width 100 characters
- Use semicolons

### Error Handling
- Always use try-catch
- Log errors
- Provide meaningful error messages

Creating Hooks ¶

hooks.json Format ¶

{
  "hooks": [
    {
      "event": "on_commit",
      "command": "npm run lint",
      "description": "Run lint check before commit"
    },
    {
      "event": "on_file_change",
      "pattern": "*.ts",
      "command": "npm run typecheck",
      "description": "Type check when TypeScript files change"
    }
  ]
}

Supported Events ¶

Event	Triggered When
`on_commit`	Committing code
`on_file_change`	File changes
`on_session_start`	Session starts
`on_command`	Command execution

Plugin Manifest ¶

plugin.json Format ¶

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My custom plugin",
  "author": "Your Name",
  "components": {
    "commands": ["commands/*.md"],
    "agents": ["agents/*.md"],
    "skills": ["skills/*/SKILL.md"],
    "hooks": "hooks/hooks.json"
  },
  "mcpServers": ".mcp.json"
}

Practical Examples ¶

Example 1: Team Code Review Plugin ¶

team-review-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── review-pr.md          # PR review command
│   ├── security-check.md     # Security check command
│   └── perf-audit.md         # Performance audit command
├── agents/
│   ├── security-reviewer.md  # Security review agent
│   └── perf-analyzer.md      # Performance analysis agent
└── skills/
    └── team-standards/
        └── SKILL.md          # Team standards skill

Example 2: Deployment Automation Plugin ¶

deploy-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── deploy-staging.md     # Deploy to staging
│   ├── deploy-prod.md        # Deploy to production
│   └── rollback.md           # Rollback command
├── hooks/
│   └── hooks.json            # Pre-deploy check hooks
└── .mcp.json                 # Kubernetes MCP config

Best Practices ¶

Command Design ¶

Single responsibility: Each command does one thing
Clear descriptions: Keep description concise
Document parameters: Use argument-hint to explain parameters
Minimal permissions: Only include necessary tools in allowed-tools
Error handling: Consider failure scenarios

Plugin Organization ¶

Modular: Organize related functionality together
Reusable: Skills should be usable by multiple commands
Documented: Add README and usage instructions
Versioned: Use semantic versioning

Security Considerations ¶

No hardcoded secrets: Use environment variables
Limit file access: Only access necessary paths
Validate input: Validate parameters
Audit logs: Log sensitive operations

Debugging Plugins ¶

# View plugin load status
/plugin list

# View command details
/help my-command

# Test command
/my-command test-argument

Next Steps ¶

Learn about MCP Servers to extend external integrations
Check CLI Tips to boost efficiency
Explore Workflow Tips to optimize development flow

Plugin System

On this page