# How Claude Plugins Are Composed of Capabilities: A Technical Deep Dive

> Explore the technical composition of Claude plugins. Learn how capabilities are structured from plugin.json, .mcp.json, and SKILL.md for powerful AI integrations.

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

---

**TLDR:** Claude plugins expose functionality through a hierarchical capability system where [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) declares high-level capabilities, [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) registers remote commands, and [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files define atomic and composite skills tagged for natural-language discovery.

The `anthropics/claude-plugins-community` repository implements a strict, data-driven composition model that transforms static configuration files into dynamic agent functionality. Understanding how Claude plugins are composed of capabilities requires examining the relationship between manifest declarations, MCP server configurations, and skill definitions that collectively enable Claude Code to discover and invoke plugin functionality through natural conversation.

## The Five-Layer Capability Architecture

Claude plugins structure their functionality across five distinct layers that progress from high-level declaration to runtime execution. Each layer contributes specific metadata that the Claude Code agent synthesizes into a flat list of invocable capabilities.

### 1. Plugin Manifest (plugin.json)

Every plugin ships a [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) file inside its `.claude-plugin` directory. This manifest declares the plugin's overall capabilities—such as tool sets, skill groups, or external services—and defines the configuration schema that users must provide during installation.

According to the marketplace index at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json), community plugins follow a standardized schema where the manifest enumerates available capability identifiers:

```json
// Minimal excerpt from a plugin manifest (plugin.json) showing declared capabilities
{
  "name": "tres-finance-plugin",
  "description": "Blockchain‑based finance tooling for Claude Code",
  "capabilities": [
    "build_query",
    "execute",
    "validate_query",
    "introspect"
  ],
  "userConfig": {
    "DEBANK_API_KEY": {
      "description": "API key for Debank data",
      "type": "string",
      "required": true
    }
  }
}

```

### 2. MCP Server Definition (.mcp.json)

For plugins that expose a Claude-Code MCP (Micro-Command-Processor) server, the [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file enumerates the remote commands that become capabilities for the agent. These commands—such as `build_query`, `execute`, and `introspect`—map directly to the capability identifiers declared in [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json).

The [`tres-finance-plugin/.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.mcp.json) file exemplifies this pattern, binding each MCP command to a concrete function that Claude can dispatch during conversation.

### 3. Skills (SKILL.md)

Inside each plugin, functional units called **skills** are described in [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files. A skill describes an **atomic capability**—such as "Create a transaction ledger entry"—and can also define **composite capabilities** that chain multiple atomic steps together.

For example, [`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) declares a specific skill for report generation, while [`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md) illustrates composite capabilities for video design workflows. Skills serve as the building blocks that agents invoke via natural-language prompts.

### 4. Capability Tags

Each skill lists one or more `tags` that categorize its capabilities (e.g., `"plugin-feedback"`, `"bug"`, `"feature"`). These tags allow Claude to surface the right capability when a user mentions a high-level intent.

In [`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), the tags table defines which capability identifiers are exposed to the agent, creating a bridge between natural language and executable functions.

### 5. Runtime Wiring

When a plugin is installed using `claude plugin install`, Claude Code reads the [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest, registers the MCP commands listed in [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json), and loads every [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md). The agent then sees a flat list of capabilities derived from the union of manifest-declared tools and skill-level tags.

## Execution Flow: From Natural Language to Capability Invocation

In practice, a Claude agent resolves a user request by mapping the natural-language intent to a capability tag, dispatching the corresponding skill or MCP command with appropriate parameters, and returning the result to the user.

If the skill defines a composite workflow, the agent chains further capabilities automatically. This design allows plugin authors to focus on *what* the plugin can do while the Claude runtime handles *how* to invoke those capabilities from conversational prompts.

When Claude invokes a capability declared by a plugin's [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md), the internal representation follows this structure:

```python

# Example: invoking a capability declared by a plugin's SKILL.md

# (the user says "Create a new expense report" → Claude maps to the tag `report-create`)

{
  "type": "tool",
  "name": "tres-report-create",
  "arguments": {
    "report_name": "Q3‑2024 Expenses",
    "period": "2024-07-01:2024-09-30"
  }
}

```

## Summary

- **Plugin Manifest**: The [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) file declares high-level capabilities and user configuration requirements.
- **MCP Registration**: The [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file binds remote commands like `build_query` and `execute` to capability identifiers.
- **Skill Definitions**: [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files in plugin subdirectories define atomic and composite capabilities as reusable functional units.
- **Tag-Based Discovery**: Capability tags in skill files enable natural-language intent mapping without exact keyword matching.
- **Runtime Synthesis**: During `claude plugin install`, the system flattens manifest tools, MCP commands, and skill tags into a unified capability list for the agent.

## Frequently Asked Questions

### What distinguishes atomic from composite capabilities in Claude plugins?

**Atomic capabilities** perform a single, indivisible operation—such as creating a database record or validating an API key. **Composite capabilities**, as implemented in files like [`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md), chain multiple atomic steps into workflows that execute sequentially. The same [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) format supports both types, with composite skills referencing other skills or MCP commands to build complex automation.

### How does Claude map natural language to specific plugin capabilities?

The runtime matches user utterances against **capability tags** defined in each [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file. When a user says "create an expense report," Claude identifies the `report-create` tag in [`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), maps it to the corresponding MCP command or skill definition, and extracts parameters from the conversation context to populate the tool arguments.

### What file is responsible for registering MCP commands in a Claude plugin?

The [`.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.mcp.json) file, located in the plugin root (e.g., [`tres-finance-plugin/.mcp.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.mcp.json)), enumerates the remote commands that become capabilities. This JSON file lists each command—such as `introspect` or `validate_query`—that Claude can dispatch to the plugin's Micro-Command-Processor server during agent execution.

### How do capability declarations differ between [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) and individual skill files?

[`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) provides a high-level inventory of all capabilities available in the plugin, serving as a contract for the Claude marketplace and user configuration. In contrast, individual [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files provide granular implementation details, parameter schemas, and tags for specific capabilities. The manifest declares *that* a plugin can `execute` queries, while the skill file defines *how* that execution translates to user-facing functionality.