Claude Code Plugin System: Skills, Hooks, and MCP

Anthropic's plugin system for Claude Code organizes four distinct types of agent capabilities — skills, subagents, lifecycle hooks, and MCP server connections — into reusable, file-based packages that require no compilation and can be distributed through standard Git repositories.

Four Capability Types, One Package Format

Each plugin is structured around a root manifest at .claude-plugin/plugin.json, which defines the plugin's name, description, and version. From there, the package may contain any combination of four capability types, each serving a different function in an agent workflow.

Skills are markdown-based instruction files that Claude selects autonomously based on task context. They can also be called explicitly via namespaced slash commands — for example, /plugin-name:skill-name — which gives developers precise control over when a skill fires. This dual invocation model matters practically: by default, every loaded skill occupies space in the context window even when not actively used. Developers who want to eliminate that passive cost can set disable-model-invocation: true in the skill's frontmatter, restricting the skill to manual command invocation only and reducing its passive context footprint to zero.

Subagents run as isolated workers in separate context boundaries, executing their own task loops independently of the primary conversation. The architecture documentation describes this as preventing the primary conversation from being overloaded — a meaningful constraint for long-running or multi-step agent tasks where context saturation is a real failure mode rather than a theoretical concern.

Hooks are event handlers that attach to specific lifecycle points in an agent workflow. When a lifecycle event fires, a hook can trigger a shell script, make an HTTP request, or launch a subagent. This makes hooks the primary mechanism for automating cross-system reactions to agent state changes without requiring the model itself to coordinate that work.

MCP Servers connect the model directly to external data sources, databases, and APIs via the Model Context Protocol. The plugin configuration references MCP server definitions through a .mcp.json field, keeping external service credentials and endpoint configurations within the plugin boundary rather than scattered across project configuration.

These four types address different layers of an agent's operational surface: skills handle what the model knows how to do, subagents handle parallel execution, hooks handle automated reactions, and MCP servers handle data access. A single plugin can bundle all four.

Distribution Paths: Official, Community, and Private

The documentation describes three distribution channels, each targeting a different trust and access scope.

The official marketplace hosts plugins under the @claude-plugins-official namespace, managed directly by Anthropic. Installation uses a GitHub-based path: /plugin install github@claude-plugins-official. These are the sanctioned core plugins for the Claude Code ecosystem, and they sit at the highest trust tier by design.

The community marketplace is hosted at anthropics/claude-plugins-community on GitHub and accepts third-party contributions that pass automated safety and validation filters. The documentation does not specify what those filters check or what the rejection criteria are, so the practical security posture of community plugins is not fully characterizable from available sources alone. Developers integrating community plugins in production environments should treat them with the same scrutiny they would apply to any third-party dependency — which is consistent with standard supply-chain hygiene for open-source agent tooling.

Teams that need private or internal distribution can host their own marketplace by placing a .claude-plugin/marketplace.json catalog in any Git repository — GitHub, GitLab, or Bitbucket. This makes the distribution mechanism identical to any other Git-hosted dependency, which lowers the operational overhead for teams already running internal package infrastructure.

What the File-Based Design Constrains and Enables

The absence of a required compilation step has a direct consequence for how plugins get written and maintained. A skill is a markdown file. A hook is a configuration entry pointing at a script or URL. An MCP server reference is a JSON field. The cognitive surface for building a basic plugin is low, and the resulting artifacts are readable without tooling.

The tradeoff is that more complex behaviors — subagents with conditional branching, hooks that chain into other hooks, skills that need to adapt based on runtime state — still require careful design. The file-based format determines how plugins are packaged and distributed, not how sophisticated they can become. The complexity ceiling is set by what Claude Code's runtime supports, not by the packaging layer.

For teams evaluating whether to build custom plugins or rely on the official marketplace, the private repository path removes the need to publish anything publicly, which may matter for plugins that encode internal tooling, proprietary workflows, or environment-specific configurations. The same Git-based mechanics that govern Anthropic's broader SDK and tooling infrastructure apply here: version control, access permissions, and auditability come from the repository host, not from a separate plugin registry service.