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

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 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.

/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, 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 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.

/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 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.

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

The 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 metadata or from a dedicated hooks.json file. The tres-settings-management skill demonstrates this pattern by referencing pre-tool and post-tool hooks to validate mutations.

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 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.

/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 file. Users activate agents via the /agent-name syntax. The Agent Discovery plugin (agent-discover) provides tools for registering and discovering these persistent entities.

/agent-discovery:list   # list all discovered agents

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

As documented in 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 files, run an MCP server configured in .mcp.json, provide validation hooks, and define persistent agents. The central manifest at .claude-plugin/marketplace.json tracks plugin metadata regardless of which patterns are implemented.

Summary

• Skill-only plugins use 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 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 file placed within the skill's directory structure. According to the 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 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 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 file, as shown in the agent-discover plugin documentation. These files configure the persistent personas activated via /agent-name commands.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}