How Claude Plugins Combine CLI Tools with Skill Bundles

Claude plugins can combine CLI tools with skill bundles through a hybrid architecture that detects local binary availability and automatically falls back to MCP-based skill bundles when the CLI is absent.

The anthropics/claude-plugins-community repository implements a sophisticated dual-mode plugin system that unifies local command-line interfaces with portable skill definitions. This architecture allows Claude agents to leverage high-performance native binaries when available while maintaining full functionality through MCP-based skill bundles in web-only environments.

Understanding the Hybrid Plugin Architecture

The Claude plugin ecosystem supports two complementary deployment mechanisms that operate seamlessly together. According to the source code in anthropics/claude-plugins-community, plugins package both a native CLI binary and a collection of .SKILL.md files, enabling the agent to select the optimal execution path based on the user's current environment.

CLI-First Plugin Implementation

CLI-first plugins distribute native binaries through standard package managers like npm or Homebrew. The plugin's metadata, defined in plugin.json, registers the binary location and exposes MCP endpoints that map directly to CLI commands.

As documented in quickdesign/README.md, the classic installation pattern follows the "npm (CLI binary + skill bundle)" model. When installed, the binary resides on the user's machine while the corresponding skill definitions populate ~/.claude/skills/, creating a unified interface that works across Claude Code and Claude Desktop.

Skill Bundle Distribution

Skill bundles consist of structured .SKILL.md files that define MCP tools, input schemas, and capability descriptions. The marketplace manifest in .claude-plugin/marketplace.json contains concrete examples of "5-skill bundles" that ship coordinated capabilities alongside CLI implementations, ensuring feature parity across deployment targets.

Runtime Decision Logic: CLI vs. MCP Fallback

The agent employs an explicit decision tree to determine whether to invoke the local CLI or utilize the skill bundle implementation. This routing logic is documented in quickdesign/skills/quickdesign/references/connecting-claude-ai-via-mcp.md.

When processing a request, Claude first checks for the presence of the CLI binary (e.g., quickdesign). If detected on the host system, the agent routes execution through the CLI path to capture live stdout/stderr, progress streams, and full feature support. If the binary is absent, the agent transparently redirects to the MCP skill bundle, which provides a functional subset of capabilities through the remote server.

Implementation Examples

The following patterns demonstrate how plugins implement this hybrid approach in practice.

Invoking CLI Commands from Skill Definitions

The SKILL.md file in quickdesign/skills/quickdesign/SKILL.md defines capabilities that map directly to CLI invocations:

description: Use the `quickdesign` CLI to generate AI media ... Invoke this skill whenever the user asks for a talking-avatar video, multi-segment ad / promo / explainer, image edit ...

When Claude receives a generation request, it constructs and executes the corresponding shell command:

quickdesign video generate --model seedance-2.0-r2v \
    --script "Our product solves X..." \
    --reference-audio ./voice.wav \
    --output ./out.mp4 --wait

The skill wrapper captures the CLI's stdout, polls for completion status, and returns the artifact URL to the user.

Fallback Mechanisms for Web Environments

For environments lacking the CLI, the same skill names map to MCP implementations. As outlined in connecting-claude-ai-via-mcp.md:

• CLI path: Requires the quickdesign binary on the host machine; provides fastest execution and richest output in Claude Code and terminals.
• MCP path: Activates when the CLI is unavailable; uses the skill bundle to call remote MCP servers with limited but functional capability subsets.

Combined Installation Workflows

Plugins distribute both components through unified installation commands:

npm install -g @quickdesign/cli       # Installs the binary

quickdesign init                      # Copies SKILL.md files to ~/.claude/skills/quickdesign/

The init command seeds the skill bundle, ensuring Claude recognizes available tools even if the user later uninstalls the binary.

Key Source Files Demonstrating the Architecture

Several critical files in the repository illustrate how Claude plugins combine CLI tools with skill bundles:

• quickdesign/README.md: Documents the "Option A — npm (CLI binary + skill bundle, classic)" installation model.
• quickdesign/skills/quickdesign/SKILL.md: Defines the bridge between natural-language intent and CLI execution.
• quickdesign/skills/quickdesign/references/connecting-claude-ai-via-mcp.md: Specifies the decision logic for routing between CLI and MCP paths.
• .claude-plugin/marketplace.json: Contains the "5-skill bundle" entry showing coordinated skill distribution.
• testdino/.claude-plugin/plugin.json: Demonstrates dual exposure of MCP tools and optional CLI integration.

Summary

• Hybrid architecture: Claude plugins combine local CLI binaries with portable skill bundles to maximize compatibility and performance across environments.
• Automatic detection: The agent checks for CLI availability at runtime, preferring native execution for full feature sets and streaming output capabilities.
• Graceful degradation: When binaries are absent, plugins fall back to MCP-based skill bundles that provide core functionality via remote servers.
• Unified interface: Users invoke the same skill names regardless of environment, with the plugin transparently handling the underlying transport mechanism.

Frequently Asked Questions

Can a Claude plugin work without installing the CLI?

Yes. According to the connecting-claude-ai-via-mcp.md reference file, plugins implement an MCP fallback path that activates when the CLI binary is not detected on the host system. While the CLI provides richer output and faster execution, the skill bundle maintains essential functionality through remote MCP servers, ensuring the plugin remains usable in web-only contexts.

How does Claude decide whether to use the CLI or the skill bundle?

The decision logic, as implemented in the QuickDesign plugin, explicitly queries the environment to determine if Claude Code is running with the CLI installed. If the binary is present and accessible at the registered path, the agent routes requests through the CLI for optimal performance; otherwise, it utilizes the MCP-based skill bundle defined in the marketplace manifest.

What files are required to implement a hybrid CLI and skill bundle plugin?

You need both a plugin.json configuration that registers the CLI binary location and MCP endpoints, plus a set of .SKILL.md files that define capabilities. The testdino/.claude-plugin/plugin.json file demonstrates this dual registration, while quickdesign/skills/quickdesign/SKILL.md shows how to structure skill definitions that bridge natural language to specific CLI commands.

Do users need to install both components separately?

Typically, no. As shown in the QuickDesign README, plugins provide unified installation commands (such as npm install followed by quickdesign init) that simultaneously install the CLI binary and copy the skill bundle to ~/.claude/skills/. This ensures both execution paths are available immediately after installation, with the agent automatically selecting the appropriate path based on context.

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