Skills-Based vs MCP-Based Claude Plugins: Key Architectural Differences

Skills-based plugins orchestrate reusable internal logic units to perform complex multi-step workflows without external dependencies, while MCP-based plugins serve as thin wrappers that leverage the Model Connector Platform to invoke external GraphQL APIs.

The anthropics/claude-plugins-community repository demonstrates two distinct patterns for extending Claude’s capabilities. Choosing between these architectures determines whether your plugin relies on Claude’s native reasoning tools or delegates operations to external services via standardized connectors.

Core Architectural Concepts

Skills-Based Architecture

A skill is a reusable, self-contained unit of logic described in a SKILL.md file. Skills-based plugins bundle one or many such skills, orchestrating them to perform complex, multi-step workflows including planning, architecture review, and bug triage. According to the marketplace manifest in .claude-plugin/marketplace.json, these plugins are characterized by descriptions like "Intelligent prompt optimization using skill-based architecture" and "A skill-based workflow plugin for planning, architecture, and bug triage" (lines 15781-15782 and 17819-17820).

Each skill may utilize Claude’s internal tools—such as code, search, and prompt—to accomplish tasks independently without requiring external API connections.

MCP-Based Architecture

MCP (Model Connector Platform) provides a standardized GraphQL interface to external APIs. MCP-based plugins primarily act as thin wrappers that invoke MCP tools—including execute, introspect, and get_viewer—to fetch or mutate data from remote services.

As implemented in the TRES Finance plugin at tres-finance-plugin/skills/tres-wallets-upload/SKILL.md, these skills explicitly declare dependencies such as "Requires TRES Finance MCP connector" and specify that "All GraphQL calls use the user-tres-finance MCP server (execute tool)" (lines 8-13).

Implementation Patterns Compared

Skills-Based Plugin Structure

Skills-based plugins define their capabilities through declarative metadata and optional pipelines. The quickdesign plugin illustrates this pattern in quickdesign/.claude-plugin/plugin.json:

{
  "name": "quickdesign",
  "description": "A skill-based workflow plugin for video design and editing.",
  "skills": [
    "quickdesign/references/voice-continuity",
    "quickdesign/references/script-and-duration",
    "quickdesign/pipelines/ugc-video"
  ]
}

This structure emphasizes internal orchestration, where Claude sequences multiple skills and may prompt users for clarification between steps.

MCP-Based Plugin Structure

MCP-based plugins embed direct tool calls within skill definitions. The TRES Finance wallet upload skill at tres-finance-plugin/skills/tres-wallets-upload/SKILL.md demonstrates this approach:

# SKILL.md excerpt

description: Upload a new wallet to TRES Finance.
compatibility: "Requires TRES Finance MCP connector"
MCP Server: All GraphQL calls use the **user-tres-finance** MCP server (`execute` tool).

Unlike skills-based implementations, this pattern contains minimal orchestration logic, focusing instead on request routing and result formatting.

Key Architectural Differences

Dependency Requirements

• Skills-based: Operates entirely within Claude without external connectors. The plugin functions independently using native tooling.
• MCP-based: Requires the corresponding MCP connector (e.g., "TRES Finance MCP") to be configured. The plugin is non-functional without this external dependency.

Flexibility and Extensibility

• Skills-based: Highly extensible through the addition, combination, or reordering of skills. New capabilities are added by creating new SKILL.md files without changing external APIs.
• MCP-based: Limited to the capabilities exposed by the MCP GraphQL schema. New functionality requires updates to the remote API rather than the plugin itself.

Typical Use Cases

• Skills-based: Complex workflows like "Generate a development plan," "Create a PRD," or "Run a multi-step video design pipeline" that require sequential reasoning and user clarification.
• MCP-based: Direct data operations such as "Create a wallet in TRES Finance," "Fetch a transaction ledger," or "Update organization settings" that map single intents to external API calls.

Summary

• Skills-based plugins utilize SKILL.md files to define reusable logic units that orchestrate Claude’s internal tools for multi-step workflows.
• MCP-based plugins depend on the Model Connector Platform to proxy user intents to external GraphQL services via standardized tools like execute.
• Skills-based architectures offer greater flexibility and independence from external systems, while MCP-based architectures provide standardized access to remote APIs.
• The choice between architectures depends on whether your use case requires rich internal reasoning (skills-based) or straightforward external API access (MCP-based).

Frequently Asked Questions

Can a single plugin combine both skills-based and MCP-based approaches?

Yes, a plugin can incorporate both patterns. While the anthropics/claude-plugins-community repository typically organizes plugins by primary architecture, the underlying system supports hybrid implementations where some skills use internal Claude tools while others invoke MCP servers. However, maintainers should clearly document which specific skills require external MCP connectors, as seen in the TRES Finance plugin's compatibility notes.

What happens if an MCP-based plugin is invoked without the required connector configured?

The plugin will fail to execute MCP-specific operations. According to the skill metadata in tres-finance-plugin/skills/tres-wallets-upload/SKILL.md, skills explicitly declare requirements like "Requires TRES Finance MCP connector" (lines 10-13). Claude will typically inform users of the missing dependency rather than attempting to execute the GraphQL calls locally, as MCP-based plugins lack the internal logic to perform these operations without the external connector.

How do I determine which architectural pattern to use for a new Claude plugin?

Evaluate your integration requirements. If your workflow involves "planning, architecture, and bug triage" using Claude’s native capabilities—as described in .claude-plugin/marketplace.json (lines 17819-17820)—choose the skills-based approach. If you need to "Create a wallet" or "Fetch a transaction ledger" from an external service like TRES Finance, implementing an MCP-based plugin at tres-finance-plugin/skills/tres-wallets-upload/SKILL.md provides the standardized GraphQL interface necessary for external data mutation.

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