Understanding the Distinction Between Skills and MCP Tools in Claude Plugin Architecture

Skills are high-level conversational workflows defined in SKILL.md files that orchestrate user interactions, while MCP tools are low-level GraphQL operations declared in plugin.json that execute specific API calls.

The anthropics/claude-plugins-community repository implements a two-layer architecture that separates user-facing conversation logic from backend API operations. Understanding the distinction between skills and MCP tools is essential for developers building custom Claude plugins, as this separation determines how user requests translate into executable code. This article examines the concrete implementation differences using source files from the official community plugins.

What Are Skills in Claude Plugins?

Skills represent composite, user-facing capabilities that describe complete business tasks through natural language triggers and step-by-step workflows.

Skill Definition via SKILL.md Files

Each skill resides in its own directory under */skills/* and contains a SKILL.md file that defines trigger phrases, required parameters, and the conversational flow. For example, in tres-finance-plugin/skills/tres-wallets-upload/SKILL.md, the skill documentation explicitly states it "creates wallets via the TRES MCP API," demonstrating how skills conceptualize high-level objectives while delegating implementation details to underlying tools.

Orchestration Logic and User Flow

Skills contain scripts that manage multi-turn conversations, validate user inputs, and determine when to invoke underlying tools. Unlike atomic functions, skills may prompt users for clarification, maintain state across interactions, and coordinate multiple API calls to fulfill a single user request. The skill layer handles the what and when of user intent translation.

What Are MCP Tools?

MCP (Model-Control-Plane) tools provide the primitive operations that connect Claude to external services through standardized GraphQL interfaces.

Low-Level GraphQL Primitives

The core MCP tools include:

• execute: Runs arbitrary GraphQL queries or mutations against the backend server
• introspect: Fetches the live GraphQL schema for dynamic query construction
• get_viewer: Retrieves the current organization and user context for authorization

These tools represent the how of technical implementation, performing single-purpose API operations without conversational context.

Manifest Declaration in plugin.json

These tools are formally declared in .claude-plugin/plugin.json files. According to the repository structure, this manifest enumerates available tools with their descriptions and types, serving as the contract between the skill orchestration layer and the connector runtime. While access restrictions prevent direct reading of these JSON files, references throughout skill documentation consistently point to this manifest as the canonical tool registry for each plugin.

Key Architectural Differences

The separation between these concepts follows a clear hierarchy:

Aspect	Skills	MCP Tools
Granularity	Coarse-grained workflows spanning multiple turns	Fine-grained, atomic GraphQL operations
User Visibility	Direct natural language interaction	Internal implementation detail
Definition Format	Human-readable markdown with business logic	Machine-readable JSON with technical specs
Reusability	Task-specific implementations	Shared across multiple skills (e.g., execute)

How Skills Invoke MCP Tools: Implementation Flow

When a user triggers a skill, the execution decomposes high-level intent into low-level API calls through a predictable pattern.

Consider the workflow defined in [tres-finance-plugin/skills/tres-wallets-upload/SKILL.md](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-wallets-upload/SKILL.md):

1. User states: "I need to onboard new wallets to my organization"
2. Claude matches this to the wallet upload skill trigger phrases
3. The skill script calls get_viewer (MCP tool) to authenticate the organization context
4. After validation, the skill constructs a GraphQL mutation and invokes the execute MCP tool
5. The skill polls for completion using subsequent execute calls
6. Final results are formatted into user-friendly responses

Code Example: Skill Orchestration Logic

# Conceptual implementation based on tres-finance-plugin skill patterns

# Located in skills/tres-wallets-upload/scripts/orchestrator.py

# Step 1: Authenticate via MCP tool

viewer_context = mcp.call_tool('get_viewer')
org_id = viewer_context['organization']['id']

# Step 2: Prepare wallet creation payload

mutation = build_wallet_mutation(org_id=org_id, wallets=user_provided_list)

# Step 3: Execute via MCP primitive

response = mcp.call_tool('execute', query=mutation)

# Step 4: Handle polling logic via additional MCP calls

while response['status'] == 'PENDING':
    check_query = build_status_query(response['jobId'])
    response = mcp.call_tool('execute', query=check_query)

return format_success_message(response)

This demonstrates how skills handle conversation state while MCP tools handle network operations, maintaining strict separation of concerns.

Repository Structure and Key Source Files

The file layout in anthropics/claude-plugins-community reflects the architectural separation:

• [tres-finance-plugin/skills/tres-wallets-upload/SKILL.md](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-wallets-upload/SKILL.md): Defines the wallet onboarding skill and references MCP API usage
• [tres-finance-plugin/skills/tres-report-create/SKILL.md](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-report-create/SKILL.md): Report generation skill utilizing execute and get_viewer tools
• tres-finance-plugin/.claude-plugin/plugin.json: Declares available MCP tools including execute, introspect, and get_viewer
• [quickdesign/.claude-plugin/plugin.json](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json): Cross-reference showing consistent tool definitions across different plugin domains
• [testdino/.claude-plugin/plugin.json](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/.claude-plugin/plugin.json): Demonstrates tool registration patterns in testing contexts

Each SKILL.md references these tools by name when describing implementation, while the plugin.json files provide the formal interface definitions consumed by the Claude runtime.

Summary

• Skills are high-level, user-facing workflows defined in SKILL.md files that handle conversation flow, parameter collection, and business logic orchestration
• MCP Tools are low-level primitives (execute, introspect, get_viewer) declared in .claude-plugin/plugin.json that perform atomic GraphQL operations against backend services
• Skills invoke MCP tools internally to fulfill requests, maintaining a clean separation between conversational AI and API integration
• Multiple skills can reuse the same MCP tool, promoting code efficiency while allowing specialized user experiences
• The repository structure consistently applies this pattern across finance, design, and testing plugins in anthropics/claude-plugins-community

Frequently Asked Questions

Can a Claude plugin skill function without MCP tools?

No. While skills define the conversational interface and workflow logic, they require MCP tools to perform any external operations. The source code analysis reveals that every SKILL.md file in the repository explicitly references MCP API calls for data persistence or retrieval. Without these low-level primitives, skills cannot interact with backend services or execute business logic.

How do I add a new capability to my Claude plugin?

Adding capabilities involves creating both architectural components: first, define a new skill by creating a SKILL.md file with trigger phrases and orchestration logic under */skills/<skill-name>/. Second, if the capability requires new API operations not covered by existing primitives, register additional MCP tools in .claude-plugin/plugin.json with proper GraphQL schema mappings and descriptions.

Are MCP tools reusable across different skills within the same plugin?

Yes. The architecture explicitly encourages reusability. For example, the execute tool appears in multiple skills across the tres-finance-plugin, serving wallet uploads, report generation, and data queries. This design prevents redundant tool definitions while allowing each skill to compose unique workflows from shared primitives like execute, introspect, and get_viewer.

Where can I find the complete list of MCP tools available to a specific plugin?

The canonical source is the .claude-plugin/plugin.json file within each plugin directory. According to the repository structure, this JSON manifest enumerates all available tools with their descriptions and types. Additionally, individual SKILL.md files reference specific tools by name when describing their implementation requirements, providing secondary documentation of available primitives.

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