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

TLDR: Claude plugins expose functionality through a hierarchical capability system where plugin.json declares high-level capabilities, .mcp.json registers remote commands, and 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 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, community plugins follow a standardized schema where the manifest enumerates available capability identifiers:

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

The 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 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 declares a specific skill for report generation, while 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, 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 manifest, registers the MCP commands listed in .mcp.json, and loads every 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, the internal representation follows this structure:

# 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 file declares high-level capabilities and user configuration requirements.
• MCP Registration: The .mcp.json file binds remote commands like build_query and execute to capability identifiers.
• Skill Definitions: 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, chain multiple atomic steps into workflows that execute sequentially. The same 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 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, 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 file, located in the plugin root (e.g., 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 and individual skill files?

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

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