Direct Answer: What is a Claude Code Plugin?
A Claude Code plugin is a self-contained, distributable package that extends the capabilities of Anthropic's terminal-based assistant. While an individual skill provides a single set of procedural instructions, a plugin acts as a Layer 2 packaging system that can bundle multiple components together: contextual agent skills (skills/), interactive slash commands (commands/), specialized subagents (agents/), automated lifecycle hooks (hooks/), and Model Context Protocol servers (.mcp.json).
Plugins are identified by a manifest file at .claude-plugin/plugin.json and can be distributed through Git repositories acting as plugin marketplaces (.claude-plugin/marketplace.json). They allow software teams to install complete engineering workflows across machines with a single command: /plugin install <plugin-name>@<marketplace-name>.
The Core Building Blocks Inside a Plugin
Unlike loose markdown files scattered across folders, a Claude Code plugin organizes your development tooling into a standardized directory structure:
1. Contextual Agent Skills (skills/)
Each subfolder contains a SKILL.md file that teaches Claude domain-specific conventions, coding rules, or testing frameworks. Claude detects and loads these instructions dynamically when your prompt matches the skill's triggers.
2. Custom Slash Commands (commands/)
Commands allow developers to define interactive terminal shortcuts (such as /commit, /pr, or /audit). Each command is written as a markdown file that instructs Claude to perform a structured prompt sequence without requiring you to retype repetitive prompts.
3. Specialized Subagents (agents/)
Subagents define dedicated personas with scoped instructions and tool access (for example, @security-reviewer or @test-architect). You can delegate subtasks to them directly in your conversation.
4. Deterministic Event Hooks (hooks/ or hooks.json)
Hooks act as automated turnstiles executing at session lifecycle events (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop). For example, a git-safety hook can intercept any attempt by Claude to run git push --force before the tool executes, providing deterministic guardrails that do not rely on model prompt adherence.
5. MCP Server Integrations (.mcp.json)
Plugins can package Model Context Protocol server configurations, connecting Claude to external issue trackers (GitHub, Linear), cloud databases, design systems (Figma), or local utilities.
Anatomy of a Plugin Directory
A standard Claude Code plugin follows this directory layout:
my-plugin/
├── .claude-plugin/
│ └── plugin.json # Required manifest metadata
├── skills/ # Modular contextual skills
│ └── code-review/
│ └── SKILL.md
├── commands/ # Slash command shortcuts
│ └── audit.md
├── agents/ # Dedicated subagents
│ └── reviewer.md
├── hooks/ # Deterministic lifecycle hooks
│ └── hooks.json
├── .mcp.json # External tool configurations
└── README.md # User documentation
The Manifest (.claude-plugin/plugin.json)
Every individual plugin requires a JSON manifest declaring its name, version, and capabilities:
{
"name": "my-plugin",
"version": "1.0.0",
"description": "Streamlines PR creation and code review guardrails for engineering teams.",
"author": { "name": "Your Name", "email": "dev@example.com" },
"license": "MIT"
}
Why Plugins Matter for Software Teams
Prior to the plugin architecture, sharing agent tooling required developers to manually copy skills into their global ~/.claude/skills/ directory, update local settings.json files for hooks, and separately register MCP servers.
Plugins solve this fragmentation by providing:
- Single-Command Setup: Install everything using
/plugin install <name>@<marketplace>. - Version Pinning & Updates: Repositories publish versioned releases, and Claude Code checks for updates in the background.
- Scoping Controls: Teams can install plugins globally (
--user), committed for a team project (--project), or strictly for the current repository (--local).
Frequently Asked Questions
Can I test a plugin locally before publishing it?
Yes. Use the--plugin-dir flag when starting Claude Code: claude --plugin-dir ./path/to/my-plugin. This loads the plugin strictly for that single session without making permanent changes to your configuration.
How do marketplaces differ from individual plugins?
A plugin is the package containing the tools, while a marketplace is a catalog registry (.claude-plugin/marketplace.json) pointing to one or more plugins. Adding a marketplace via /plugin marketplace add <repo> allows you to discover and install all packages published in that repository.
Are plugins secure to run?
Because plugins can define automated event hooks and shell commands, you should always audit the repository and review the.claude-plugin/plugin.json file before installing. SkillHub statically scans every listed plugin for dangerous patterns and highlights permissions upfront.