157 lines
5.3 KiB
Markdown
157 lines
5.3 KiB
Markdown
---
|
|
title: "Creating Claude Code Plugins"
|
|
aliases: [claude-code-plugins, plugin-authoring, claude-plugins]
|
|
tags: [claude-code, plugins, skills, agents, hooks, mcp, extensibility]
|
|
sources: [raw/Create plugins.md]
|
|
created: 2026-04-17
|
|
updated: 2026-04-17
|
|
---
|
|
|
|
# Creating Claude Code Plugins
|
|
|
|
Plugins package skills, agents, hooks, MCP servers, LSP servers, and background monitors into a shareable, versioned unit. They are the distribution mechanism for Claude Code extensions.
|
|
|
|
## Standalone Config vs. Plugins
|
|
|
|
| Approach | Skill names | Best for |
|
|
|----------|-------------|----------|
|
|
| **Standalone** (`.claude/` dir) | `/hello` | Personal workflows, single-project, quick experiments |
|
|
| **Plugin** (dir with `.claude-plugin/plugin.json`) | `/my-plugin:hello` | Team sharing, multi-project reuse, marketplace distribution |
|
|
|
|
- Start standalone → convert to plugin when ready to share
|
|
- Plugins namespace skill names (`/plugin-name:skill`) to prevent conflicts
|
|
|
|
## Plugin Directory Structure
|
|
|
|
```
|
|
my-plugin/
|
|
├── .claude-plugin/
|
|
│ └── plugin.json ← manifest (ONLY file inside .claude-plugin/)
|
|
├── skills/
|
|
│ └── code-review/
|
|
│ └── SKILL.md
|
|
├── commands/ ← legacy flat .md skills (use skills/ for new)
|
|
├── agents/ ← custom agent definitions
|
|
├── hooks/
|
|
│ └── hooks.json
|
|
├── monitors/
|
|
│ └── monitors.json
|
|
├── bin/ ← executables added to PATH
|
|
├── .mcp.json ← MCP server configs
|
|
├── .lsp.json ← LSP server configs
|
|
└── settings.json ← default settings when plugin enabled
|
|
```
|
|
|
|
**Critical mistake to avoid:** Never put `skills/`, `agents/`, `hooks/`, or `commands/` inside `.claude-plugin/`. Only `plugin.json` lives there.
|
|
|
|
## Plugin Components
|
|
|
|
### Skills
|
|
- Add `skills/<name>/SKILL.md` at plugin root
|
|
- Include `description:` in frontmatter so Claude knows when to invoke
|
|
- Model-invoked automatically based on task context
|
|
- Run `/reload-plugins` after changes
|
|
|
|
```yaml
|
|
---
|
|
description: Reviews code for best practices. Use when reviewing PRs or analyzing code quality.
|
|
---
|
|
|
|
When reviewing code, check for:
|
|
1. Error handling
|
|
2. Security concerns
|
|
3. Test coverage
|
|
```
|
|
|
|
### LSP Servers
|
|
- Add `.lsp.json` at plugin root for language intelligence
|
|
- Users must have the language server binary installed
|
|
- Use pre-built marketplace LSP plugins for common languages (TS, Python, Rust)
|
|
|
|
```json
|
|
{
|
|
"go": {
|
|
"command": "gopls",
|
|
"args": ["serve"],
|
|
"extensionToLanguage": { ".go": "go" }
|
|
}
|
|
}
|
|
```
|
|
|
|
### Background Monitors
|
|
- Add `monitors/monitors.json` — array of monitor entries
|
|
- Each stdout line from `command` is delivered to Claude as a notification
|
|
- Started automatically when plugin is active
|
|
|
|
```json
|
|
[
|
|
{
|
|
"name": "error-log",
|
|
"command": "tail -F ./logs/error.log",
|
|
"description": "Application error log"
|
|
}
|
|
]
|
|
```
|
|
|
|
### Default Settings
|
|
- `settings.json` at plugin root applies config when plugin is enabled
|
|
- Supported keys: `agent`, `subagentStatusLine`
|
|
- Setting `agent` activates a plugin agent as the main thread
|
|
|
|
```json
|
|
{ "agent": "security-reviewer" }
|
|
```
|
|
|
|
## Testing Locally
|
|
|
|
```shell
|
|
# Load one plugin
|
|
claude --plugin-dir ./my-plugin
|
|
|
|
# Load multiple plugins
|
|
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two
|
|
```
|
|
|
|
- Local `--plugin-dir` takes precedence over installed marketplace plugins of the same name
|
|
- Run `/reload-plugins` during development to pick up changes without restart
|
|
- Test skills: `/plugin-name:skill-name` | Check agents: `/agents`
|
|
|
|
## Migrating from Standalone to Plugin
|
|
|
|
| Standalone (`.claude/`) | Plugin |
|
|
|-------------------------|--------|
|
|
| Available in one project | Shareable via marketplace |
|
|
| `commands/` in `.claude/` | `commands/` at plugin root |
|
|
| Hooks in `settings.json` | `hooks/hooks.json` |
|
|
| Manual copy to share | Install with `/plugin install` |
|
|
|
|
After migrating, remove original `.claude/` files to avoid duplicates.
|
|
|
|
## Distribution
|
|
|
|
1. Add `README.md` with install + usage instructions
|
|
2. Use semantic versioning in `plugin.json`
|
|
3. Submit to official marketplace via `claude.ai/settings/plugins/submit` or `platform.claude.com/plugins/submit`
|
|
4. Distribute through a plugin marketplace (official or team-hosted)
|
|
|
|
## Key Takeaways
|
|
|
|
- Plugin root structure: manifest in `.claude-plugin/plugin.json`, everything else at root level
|
|
- Skills are model-invoked; slash commands are user-invoked — they live in different dirs (`skills/` vs `commands/`)
|
|
- Use `--plugin-dir` for local testing; run `/reload-plugins` to hot-reload changes
|
|
- Background monitors run automatically and stream stdout lines to Claude as notifications
|
|
- `settings.json` can activate a plugin agent as the default main-thread agent
|
|
- Start with standalone `.claude/` config, convert to plugin when ready to distribute
|
|
- Plugin skill names are always namespaced: `/plugin-name:skill-name`
|
|
|
|
## Related
|
|
|
|
- [[wiki/claude-code/custom-subagents|Custom Subagents]] — agent definitions used inside plugins
|
|
- [[wiki/claude-code/mcp-integration|MCP Integration]] — `.mcp.json` for adding MCP servers to a plugin
|
|
- [[wiki/claude-code/overview|Claude Code Overview]] — full product context
|
|
- [[wiki/agent-sdk/_index|Agent SDK]] — building agents that plugins can wrap
|
|
|
|
## Sources
|
|
|
|
- Source: `raw/Create plugins.md`
|
|
- Original: https://code.claude.com/docs/en/plugins
|