Claude Code Plugins

1. What Is a Claude Code Plugin?

Think of a plugin like a toolbox. Your toolbox can contain several reusable tools, and Claude Code can load that toolbox when you need it.

Why Plugins?

2. Plugin vs Standalone .claude/

Claude Code supports both standalone configuration and plugins. A useful beginner rule is: start locally, package when you want to share.

Approach	Example name	Best for
Standalone .claude/	/hello	One project, personal customization, experiments and quick iteration.
Plugin	/my-plugin:hello	Team/community sharing, reusable capabilities, versioned releases and marketplaces.

3. Create Your First Plugin

Step 1 — Create the plugin directory

mkdir my-first-plugin

A plugin is a self-contained directory. The directory can contain its manifest and the components you want to ship.

Step 2 — Create the manifest

mkdir my-first-plugin/.claude-plugin

Create:

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	Meaning
name	Plugin identity and the namespace used by plugin Skills.
description	Description shown in the plugin manager.
version	Optional version. If used, bump it when you want version-based updates.
author	Optional attribution information.

Step 3 — Add a Skill

mkdir -p my-first-plugin/skills/hello

Create:

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.

The folder name hello becomes the Skill name. Because the plugin is named my-first-plugin, the invocation becomes:

/my-first-plugin:hello

Step 4 — Test the plugin

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

Then inside Claude Code:

/my-first-plugin:hello

You can also use /help to find the Skill under the plugin namespace.

Step 5 — Make the Skill dynamic

The $ARGUMENTS placeholder captures text supplied after the Skill name.

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

# Hello Skill

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

Now:

/my-first-plugin:hello Alex

The Skill can use Alex as the argument supplied by the user. After changing the plugin, use:

/reload-plugins

4. Plugin Structure

A plugin can grow from one simple Skill into a complete development toolkit.

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── code-review/
│       └── SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/
│   └── hooks.json
├── .mcp.json
├── .lsp.json
├── monitors/
│   └── monitors.json
├── bin/
└── settings.json

Path	Purpose
.claude-plugin/	Contains plugin.json manifest.
skills/	Skills stored as folders containing SKILL.md.
commands/	Flat Markdown command files; Skills directory is preferred for new plugins.
agents/	Custom agent definitions.
hooks/	Event handlers, typically configured in hooks.json.
.mcp.json	MCP server configurations.
.lsp.json	LSP server configurations for code intelligence.
monitors/	Background monitor configuration.
bin/	Executables added to Bash PATH while the plugin is enabled.
settings.json	Default settings applied when the plugin is enabled.

5. Plugin Components Explained Simply

Skills inside a plugin

my-plugin/
├── .claude-plugin/plugin.json
└── skills/
    └── code-review/
        └── SKILL.md

The Skill's description helps Claude understand when it should use the Skill. For example:

---
description: Reviews code for best practices and potential issues.
Use when reviewing code, checking PRs, or analyzing code quality.
---

When reviewing code, check:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage

LSP plugin example

The documentation shows that an LSP plugin can define a language server in .lsp.json. For example:

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

Background monitor example

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

A background monitor can watch logs, files or external status. Each stdout line from the configured command can be delivered to Claude as a notification during the session.

6. Develop a Plugin in the Skills Directory

Instead of passing --plugin-dir every time, Claude Code can scaffold a plugin in the skills directory:

claude plugin init my-tool

The current documentation describes this as creating ~/.claude/skills/my-tool/ with a manifest and starter Skill. On the next session it can load as my-tool@skills-dir.

7. Ship Default Settings

A plugin can include settings.json at its root. The current documentation states that the supported keys here are agent and subagentStatusLine.

{
  "agent": "security-reviewer"
}

This example activates the plugin's security-reviewer custom agent as the main thread, applying that agent's system prompt, tool restrictions and model.

8. Test Plugins Locally

Basic local test

claude --plugin-dir ./my-plugin

This loads the plugin directly without requiring a normal installation.

Test a ZIP

claude --plugin-dir ./my-plugin.zip

Load multiple plugins

claude --plugin-dir ./plugin-one \
  --plugin-dir ./plugin-two

Reload after changes

/reload-plugins

The reload operation can reload plugin-related Skills, agents, hooks, plugin MCP servers and plugin LSP servers. Some non-interactive MCP changes may wait until the next session.

Testing checklist

• Try each Skill using its namespaced name.
• Check that custom agents are visible.
• Trigger hooks and verify their effects.
• Check the plugin manager's Errors tab when something fails.
• Use debug logging when configuration problems are unclear.

URL-hosted ZIP testing

claude --plugin-url https://example.com/my-plugin.zip

This loads a packaged ZIP for that session. Only use URLs for plugin archives you control or trust.

9. Folder of Plugins

Current Claude Code versions can also load a folder containing multiple plugins. The documentation notes that this behavior requires Claude Code v2.1.265 or later.

plugins/
├── java-tools/
│   └── .claude-plugin/plugin.json
├── frontend-tools/
│   └── .claude-plugin/plugin.json
└── security-tools/
    └── .claude-plugin/plugin.json

claude --plugin-dir ./plugins

Claude Code examines the folder's immediate subfolders. A subfolder with a valid .claude-plugin/plugin.json can load as a plugin.

10. Share Your Plugin

When the plugin is ready for other people:

Recommended sharing steps

1. Add a README.md with installation and usage instructions.
2. Choose a versioning strategy.
3. Create or use a plugin marketplace.
4. Have teammates test the plugin before wider distribution.

11. Official and Community Marketplaces

Marketplace	Purpose	Important point
claude-plugins-official	Curated official Anthropic plugins.	Anthropic decides what is included; there is no normal application process for inclusion.
claude-community	Public community marketplace for third-party submissions.	Submissions go through review and automated safety screening.

Users can add the community marketplace with:

/plugin marketplace add anthropics/claude-plugins-community

Before submitting a plugin, validate it locally:

claude plugin validate ./your-plugin

Strict validation can treat warnings as errors:

claude plugin validate ./your-plugin --strict

12. Convert Existing .claude/ Configuration to a Plugin

Suppose you already have a project with:

.claude/
├── commands/
├── agents/
├── skills/
└── settings.json

You can package those capabilities into a plugin.

Step 1 — Create the plugin

mkdir -p my-plugin/.claude-plugin

Step 2 — Create the manifest

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

Step 3 — Copy existing directories

cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/

Step 4 — Migrate hooks

mkdir my-plugin/hooks

Create my-plugin/hooks/hooks.json and move the hooks configuration from the existing settings into the plugin's hooks configuration.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
          }
        ]
      }
    ]
  }
}

Step 5 — Test the migrated plugin

claude --plugin-dir ./my-plugin

13. Standalone vs Plugin After Migration

Standalone	Plugin
Usually tied to one project.	Can be shared through marketplaces.
Commands under .claude/commands/.	Commands/Skills live under the plugin root.
Hooks in settings.	Hooks can live in hooks/hooks.json.
Manual copying for sharing.	Install and distribute as a plugin.
Skill can be /skill-name.	Plugin Skill becomes /plugin-name:skill-name.

14. Real-World Example — Java/Spring Boot Team Plugin

Imagine a team building Spring Boot applications. They repeatedly want Claude to perform the same checks:

A conceptual plugin could look like:

company-java-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── spring-review/
│   │   └── SKILL.md
│   └── test-review/
│       └── SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/
│   └── hooks.json
└── settings.json

Then the team can reuse the same package across many repositories rather than rebuilding the configuration each time.

15. Example — Next.js Frontend Team Plugin

For a frontend team, a plugin might package capabilities around:

frontend-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── component-review/
│   │   └── SKILL.md
│   ├── accessibility-review/
│   │   └── SKILL.md
│   └── performance-review/
│       └── SKILL.md
├── agents/
│   └── frontend-reviewer.md
└── hooks/
    └── hooks.json

16. Common Mistakes

Mistake	Why it is a problem	Better approach
Putting skills/ inside .claude-plugin/	Components belong at the plugin root.	Use plugin/skills/.
Forgetting plugin.json	The plugin may not have the expected identity/metadata.	Create the manifest when using the manifest-based layout.
Testing only after marketplace publication	Feedback cycle becomes slow.	Use --plugin-dir during development.
Changing files but not reloading	Current session may still use the old plugin state.	Use /reload-plugins when appropriate.
Assuming LSP binary is installed	Plugin configuration does not install the language server.	Ensure the required binary exists on the user's machine.
Trusting every third-party plugin	Plugins can contain powerful functionality.	Review and trust the source before installing.
Duplicating migrated configuration	Standalone and plugin copies may both remain active.	Clean up the original configuration after verifying migration.

17. A Good Plugin Development Workflow

1. Start with a small Skill or configuration.
2. Create the plugin directory and manifest.
3. Add only the components you really need.
4. Test with --plugin-dir.
5. Use /reload-plugins during iteration.
6. Validate before submission.
7. Document installation and usage.
8. Distribute through an appropriate marketplace.

18. Plugin vs Skill vs Agent vs Hook vs MCP

Thing	Think of it as	Main purpose
Skill	A reusable instruction/workflow	Teach Claude how to perform a repeatable task.
Agent	A specialized worker	Give Claude a focused role/configuration.
Hook	An event reaction	Run behavior when a matching Claude Code event occurs.
MCP	An external tool connection	Connect Claude Code to external tool servers.
LSP	Code intelligence	Provide language-server based understanding of code.
Monitor	A background watcher	Watch logs/files/status and notify Claude.
Plugin	A package/toolbox	Bundle and distribute these capabilities together.

19. Quick Cheat Sheet

Goal	Command / File
Create plugin directory	mkdir my-plugin
Create manifest directory	mkdir my-plugin/.claude-plugin
Manifest	.claude-plugin/plugin.json
Skill	skills/name/SKILL.md
Test plugin	claude --plugin-dir ./my-plugin
Test ZIP	claude --plugin-dir ./my-plugin.zip
Reload changes	/reload-plugins
Plugin URL	claude --plugin-url https://...
Initialize skills-directory plugin	claude plugin init my-tool
Validate	claude plugin validate ./your-plugin
Strict validation	claude plugin validate ./your-plugin --strict
Community marketplace	/plugin marketplace add anthropics/claude-plugins-community

20. Interview / Revision Questions

1. What problem does a Claude Code plugin solve?
2. When should you use standalone .claude/ configuration instead of a plugin?
3. What is the purpose of .claude-plugin/plugin.json?
4. Why are plugin Skills namespaced?
5. How do you test a plugin without installing it?
6. What does $ARGUMENTS do inside a Skill?
7. Where should skills/ live?
8. What is an LSP plugin used for?
9. Why must the LSP binary be installed separately?
10. What are background monitors used for?
11. How do you reload plugin changes?
12. How do you validate a plugin before submission?
13. What is the difference between the official and community marketplaces?
14. How can an existing .claude/ setup be migrated into a plugin?

21. Practice Exercises

22. Final Memory Map

23. Final Takeaway

Claude Code plugins are best understood as reusable extension packages. They give you a structured way to move from a small personal Claude Code customization to something that can be reused across projects and shared with a team or community.

If you remember only three things, remember:

1. .claude/ is excellent for local/project experimentation.
2. A plugin packages reusable Claude Code capabilities for distribution.
3. Test locally with --plugin-dir before sharing.