# Claude Plugin Architecture Patterns: 6 Implementation Strategies for Extending Claude Code

> Explore six Claude plugin architecture patterns including skill-only, MCP-server, hook-based, and agent-based. Learn how to extend Claude code with these implementation strategies.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: architecture
- Published: 2026-09-04

---

**Claude Code and Claude Cowork support six distinct plugin architecture patterns—skill-only, multi-skill, MCP-server, hook-based, pipeline, and agent-based—that developers can combine to create everything from simple slash commands to complex multi-agent workflows.**

The `anthropics/claude-plugins-community` repository defines the canonical implementations of these plugin architecture patterns. Each pattern addresses specific extension needs, ranging from self-contained prompt templates to persistent autonomous agents, and can be identified by their characteristic configuration files and directory structures.

## Simple Skill-Based Patterns

The most accessible entry points into Claude's plugin ecosystem rely on declarative skill definitions that require no external infrastructure.

### Skill-Only Plugins

A **skill-only plugin** encapsulates a single slash-command—such as `/quickdesign`—that contains a self-contained prompt, optional reference files, and a behavior description. These plugins run entirely inside Claude Code without requiring an external server.

The skill definition resides in a [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file. When placed in the correct directory structure, Claude Code loads the skill automatically at runtime. This pattern suits simple, reproducible actions like generating design briefs, creating architecture decision records (ADRs), or running quick analyses.

```text
/quickdesign "Create a short 30-second Instagram ad for a new sneaker"

```

The above command invokes the skill defined in [`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md), which executes entirely within Claude Code's context window.

### Multi-Skill Plugins

A **multi-skill plugin** bundles multiple related skills within a single directory, where each skill maintains its own [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file. These skills share common reference files and can invoke one another, creating cohesive tool-sets.

Claude discovers each skill independently, while the parent plugin folder registers as a single entity in the marketplace. The TRES Finance plugin exemplifies this pattern, providing dozens of finance-related commands such as `/tres-wallets-upload`, `/tres-report-create`, and `/tres-settings-management` from a unified directory.

```text
/tres-wallets-upload   # upload a batch of wallets

/tres-report-create    # generate a financial report

/tres-settings-management   # view or change org settings

```

All commands live under the `tres-finance-plugin/` directory, sharing infrastructure while exposing distinct entry points.

## External Integration Patterns

For scenarios requiring live data or external system manipulation, Claude supports server-backed patterns that extend capabilities beyond the local context.

### MCP-Server (Tool-Exposing) Plugins

**MCP-server plugins** run a Model Context Protocol (MCP) server—part of the Claude Plugin Framework—that exposes GraphQL-style tools Claude can invoke via helper methods like `execute`, `introspect`, and `build_query`.

The server configuration lives in a [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file. Claude discovers the server at runtime and treats its exposed tools as native capabilities. This pattern supports complex integrations such as querying blockchain ledgers, submitting transactions, or managing organization settings.

```text
execute {
  query: "query GetViewer { get_viewer { orgName } }"
}

```

The [`tres-finance-plugin/.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.mcp.json) file defines this configuration, enabling Claude to interact with the TRES Finance backend through structured queries.

### Hook-Based Plugins

**Hook-based plugins** implement scripts that execute automatically before (`PreToolUse`) or after (`PostToolUse`) a tool invocation. These hooks validate arguments, enforce security guardrails, or mutate output data.

Hook scripts are referenced either from a skill's [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) metadata or from a dedicated [`hooks.json`](https://github.com/anthropics/claude-plugins-community/blob/main/hooks.json) file. The `tres-settings-management` skill demonstrates this pattern by referencing pre-tool and post-tool hooks to validate mutations.

```text
pre_tool_use {
  tool: "updateSubTransaction"
  script: "./hooks/validate_update.sh"
}

```

This enforcement mechanism ensures that arguments meet security policies before Claude executes sensitive operations like `updateSubTransaction`.

## Workflow Orchestration Patterns

Advanced deployments utilize plugins that coordinate multiple capabilities across time and organizational boundaries.

### Pipeline (Orchestrator) Plugins

**Pipeline plugins** implement orchestrator skills that coordinate sequences of sub-skills or MCP tool calls, creating multi-step workflows with human-gate checkpoints between phases.

The orchestrator skill's [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) contains a high-level workflow description and invokes other skills via standard slash-command syntax. The `10x-team` orchestrator exemplifies this pattern, running twelve role-specific sub-skills—`/cto`, `/architect`, `/sde`, through `/sre`—in sequence.

```text
/10x-team   # runs 12 role-specific sub-skills in order:

            # /cto → /architect → /sde → … → /sre

```

This pattern implements end-to-end workflows such as "design → blueprint → implement → review → deploy" while requiring human approval between critical phases.

### Agent-Based Plugins

**Agent-based plugins** define named Claude Code agents—persistent personas with dedicated configurations, role-specific slash commands, and optional MCP tools. These agents function as specialist collaborators within larger teams.

Agent definitions are stored in `.claude-plugin/agents/` or within the plugin's [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) file. Users activate agents via the `/agent-name` syntax. The Agent Discovery plugin (`agent-discover`) provides tools for registering and discovering these persistent entities.

```text
/agent-discovery:list   # list all discovered agents

/agent-discovery:install agent-archive   # install the Agent Archive agent

```

As documented in [`agent-discover/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/agent-discover/README.md), this pattern enables multi-agent setups where specialized agents collaborate on complex tasks.

## Mixing and Matching Patterns

These architecture patterns are not mutually exclusive. A single plugin may simultaneously expose skills through [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files, run an MCP server configured in [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json), provide validation hooks, and define persistent agents. The central manifest at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) tracks plugin metadata regardless of which patterns are implemented.

## Summary

- **Skill-only plugins** use [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files to define single slash-commands without external servers.
- **Multi-skill plugins** bundle related skills in one directory, sharing references and marketplace registration.
- **MCP-server plugins** expose GraphQL-style tools via [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) configuration for live data integration.
- **Hook-based plugins** enforce policies through `PreToolUse` and `PostToolUse` scripts referenced in skill metadata.
- **Pipeline plugins** orchestrate multi-step workflows with human gates using coordinator skills.
- **Agent-based plugins** create persistent personas stored in `.claude-plugin/agents/` for specialized team roles.

## Frequently Asked Questions

### What file defines a skill-only plugin?

A skill-only plugin is defined by a [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file placed within the skill's directory structure. According to the [`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md) source, this file contains the prompt template, references, and behavior description that Claude Code loads automatically.

### How does an MCP-server plugin differ from a skill-only plugin?

An MCP-server plugin requires a [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) configuration file and runs an external Model Context Protocol server that exposes tools like `execute` and `introspect`, whereas a skill-only plugin operates entirely within Claude Code's context using only a [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file without external infrastructure.

### Can I combine multiple architecture patterns in one plugin?

Yes. The `tres-finance-plugin` demonstrates this by combining multi-skill organization with MCP-server capabilities and hook-based validation. Plugins may expose skills, run MCP servers, provide hooks, and define agents simultaneously.

### Where are agent definitions stored in the repository?

Agent definitions are stored in the `.claude-plugin/agents/` directory or within a plugin's [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) file, as shown in the `agent-discover` plugin documentation. These files configure the persistent personas activated via `/agent-name` commands.