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

> Learn the difference between high-level skills and low-level MCP tools in Claude plugin architecture. Understand how skills orchestrate interactions and MCP tools execute API calls.

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

---

**Skills are high-level conversational workflows defined in [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files that orchestrate user interactions, while MCP tools are low-level GraphQL operations declared in [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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)](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

```python

# 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)](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)](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`](https://github.com/anthropics/claude-plugins-community/blob/main/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)](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)](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/.claude-plugin/plugin.json)**: Demonstrates tool registration patterns in testing contexts

Each [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) references these tools by name when describing implementation, while the [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files reference specific tools by name when describing their implementation requirements, providing secondary documentation of available primitives.