When to use plugins vs standalone configuration
Claude Code supports two ways to add custom skills, agents, and hooks:
| Approach | Skill 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 |
- You're customizing Claude Code for a single project
- The configuration is personal and doesn't need to be shared
- You're experimenting with skills or hooks before packaging them
- You want short skill names like
/helloor/deploy
- You want to share functionality with your team or community
- You need the same skills/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 skills like
/my-plugin:hello(namespacing prevents conflicts between plugins)
Start with standalone configuration in
.claude/ for quick iteration, then convert to a plugin when you're ready to share. Quickstart
This quickstart walks you through creating a plugin with a custom skill. You'll create a manifest (the configuration file that defines your plugin), add a skill, and test it locally using the --plugin-dir flag.
Prerequisites
- Claude Code installed and authenticated
- Claude Code version 1.0.33 or later (run
claude --versionto check)
If you don't see the
/plugin command, update Claude Code to the latest version. See Troubleshooting for upgrade instructions. Create your first plugin
1
Create the plugin directory
Every plugin lives in its own directory containing a manifest and your skills, agents, or hooks. Create one now:
mkdir my-first-plugin
2
Create the plugin manifest
The manifest file at Then create
For additional fields like
.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
my-first-plugin/.claude-plugin/plugin.json with this content:my-first-plugin/.claude-plugin/plugin.json
{
"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 skill namespace. Skills 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. |
homepage, repository, and license, see the full manifest schema.3
Add a skill
Skills live in the Then create
skills/ directory. Each skill is a folder containing a SKILL.md file. The folder name becomes the skill name, prefixed with the plugin's namespace (hello/ in a plugin named my-first-plugin creates /my-first-plugin:hello).Create a skill directory in your plugin folder:mkdir -p my-first-plugin/skills/hello
my-first-plugin/skills/hello/SKILL.md with this content:my-first-plugin/skills/hello/SKILL.md
---
description: Greet the user with a friendly message
disable-model-invocation: true
---
Greet the user warmly and ask how you can help them today.
4
Test your plugin
Run Claude Code with the Once Claude Code starts, try your new skill:You'll see Claude respond with a greeting. Run
--plugin-dir flag to load your plugin:claude --plugin-dir ./my-first-plugin
/my-first-plugin:hello
/help to see your skill listed under the plugin namespace.Why namespacing? Plugin skills are always namespaced (like
/greet:hello) to prevent conflicts when multiple plugins have skills with the same name.To change the namespace prefix, update the name field in plugin.json.5
Add skill arguments
Make your skill dynamic by accepting user input. The Run Claude will greet you by name. For more on passing arguments to skills, see Skills.
$ARGUMENTS placeholder captures any text the user provides after the skill name.Update your SKILL.md file:my-first-plugin/skills/hello/SKILL.md
---
description: Greet the user with a personalized message
---
# Hello Skill
Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.
/reload-plugins to pick up the changes, then try the skill with your name:/my-first-plugin:hello Alex
- Plugin manifest (
.claude-plugin/plugin.json): describes your plugin's metadata - Skills directory (
skills/): contains your custom skills - Skill arguments (
$ARGUMENTS): captures user input for dynamic behavior
The
--plugin-dir flag is useful for development and testing. When you're ready to share your plugin with others, see Create and distribute a plugin marketplace. Plugin structure overview
You've created a plugin with a skill, but plugins can include much more: custom agents, hooks, MCP servers, and LSP servers.
Common mistake: Don't put
commands/, agents/, skills/, or hooks/ inside the .claude-plugin/ directory. Only plugin.json goes inside .claude-plugin/. All other directories must be at the plugin root level.| Directory | Location | Purpose |
|---|---|---|
.claude-plugin/ | Plugin root | Contains plugin.json manifest (optional if components use default locations) |
commands/ | Plugin root | Skills 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 |
settings.json | Plugin root | Default settings applied when the plugin is enabled |
Next steps: Ready to add more features? Jump to Develop more complex plugins to add agents, hooks, MCP servers, and LSP servers. For complete technical specifications of all plugin components, see Plugins reference.
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 automatically uses them based on the task context.
Add a skills/ directory at your plugin root with Skill folders containing SKILL.md files:
my-plugin/
+-- .claude-plugin/
| +-- plugin.json
+-- skills/
+-- code-review/
+-- SKILL.md
SKILL.md needs frontmatter with name and description fields, followed by instructions:
---
name: code-review
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---
When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage
/reload-plugins to load the Skills. For complete Skill authoring guidance including progressive disclosure and tool restrictions, see Agent Skills.
Add LSP servers to your plugin
For common languages like TypeScript, Python, and Rust, install the pre-built LSP plugins from the official marketplace. Create custom LSP plugins only when you need support for languages not already covered.
.lsp.json file to your plugin:
.lsp.json
{
"go": {
"command": "gopls",
"args": ["serve"],
"extensionToLanguage": {
".go": "go"
}
}
}
Ship default settings with your plugin
Plugins can include a settings.json file at the plugin root to apply default configuration when the plugin is enabled. Currently, only the agent key is supported.
Setting agent activates one of the plugin's custom agents as the main thread, applying its system prompt, tool restrictions, and model. This lets a plugin change how Claude Code behaves by default when enabled.
settings.json
{
"agent": "security-reviewer"
}
security-reviewer agent defined in the plugin's agents/ directory. Settings from settings.json take priority over settings declared in plugin.json. Unknown keys are silently ignored.
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
--plugin-dir plugin has the same name as an installed marketplace plugin, the local copy takes precedence for that session. This lets you test changes to a plugin you already have installed without uninstalling it first. Marketplace plugins force-enabled by managed settings are the only exception and cannot be overridden.
As you make changes to your plugin, run /reload-plugins to pick up the updates without restarting. This reloads commands, skills, agents, hooks, plugin MCP servers, and plugin LSP servers. Test your plugin components:
- Try your skills with
/plugin-name:skill-name - Check that agents appear in
/agents - Verify hooks work as expected
You can load multiple plugins at once by specifying the flag multiple times:
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two
Debug plugin issues
If your plugin isn't working as expected:
- Check the structure: Ensure your directories are at the plugin root, not inside
.claude-plugin/ - Test components individually: Check each command, agent, and hook separately
- 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:
- Add documentation: Include a
README.mdwith installation and usage instructions - Version your plugin: Use semantic versioning in your
plugin.json - Create or use a marketplace: Distribute through plugin marketplaces for installation
- Test with others: Have team members test the plugin before wider distribution
Submit your plugin to the official marketplace
To submit a plugin to the official Anthropic marketplace, use one of the in-app submission forms:
- Claude.ai: claude.ai/settings/plugins/submit
- Console: platform.claude.com/plugins/submit
For complete technical specifications, debugging techniques, and distribution strategies, see Plugins reference.
Convert existing configurations to plugins
If you already have 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:Create the manifest file at
mkdir -p my-plugin/.claude-plugin
my-plugin/.claude-plugin/plugin.json: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:Create
mkdir my-plugin/hooks
my-plugin/hooks/hooks.json with your hooks configuration. Copy the hooks object from your .claude/settings.json or settings.local.json, since the format is the same. The command receives hook input as JSON on stdin, so use jq to extract the file path:my-plugin/hooks/hooks.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
}
]
}
}
4
Test your migrated plugin
Load your plugin to verify everything works:Test each component: run your commands, check agents appear in
claude --plugin-dir ./my-plugin
/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 |
After migrating, you can remove the original files from
.claude/ to avoid duplicates. The plugin version will take precedence when loaded. Next steps
Now that you understand Claude Code's plugin system, here are suggested paths for different goals:
For plugin users
- Discover and install plugins: browse marketplaces and install plugins
- Configure team marketplaces: set up repository-level plugins for your team
For plugin developers
- Create and distribute a marketplace: package and share your plugins
- Plugins reference: complete technical specifications
- Dive deeper into specific plugin components: