# How the Quickdesign CLI and Claude Code Skill Interactive: A Deep Technical Guide

> Discover how the Quickdesign CLI and Claude Code skill interact. Learn about their roles in media generation and how the skill invokes the CLI locally or falls back to a remote server.

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

---

**The `quickdesign` CLI and Claude Code skill are tightly coupled components of the same media-generation system—the skill acts as a decision layer that automatically invokes the local CLI when available, falling back to a remote MCP server for web-only users.**

This guide explains the architecture, execution paths, and runtime behavior of the `quickdesign` package in the `anthropics/claude-plugins-community` repository. The `quickdesign` binary and its companion Claude Code skill share the same backend service but expose it through two different interfaces depending on where the user is running.

## How the Quickdesign CLI Architecture Works

The `quickdesign` binary is a thin wrapper around the hosted QuickDesign **MCP** (media-creation-platform) service. It handles the full lifecycle of media generation:

- Authenticates users via `quickdesign auth login`
- Discovers available models with `quickdesign video models`
- Computes generation costs before spending credits
- Polls jobs and uploads finished assets to stable storage

All API keys remain hidden—the CLI manages OAuth tokens internally.

## Installing the Claude Code Skill from the CLI

When you run `quickdesign init`, the installer copies the bundled skill into your local Claude Code environment.

```bash

# Installs SKILL.md and reference docs to Claude Code

quickdesign init

```

Per [`quickdesign/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/README.md) (lines 27-33), this copies files to:

```

~/.claude/skills/quickdesign/
├── SKILL.md                    # Core skill definition

├── references/                 # MCP fallback documentation

└── models/                     # Model cards like seedance-2.0-r2v.md

```

Claude Code auto-loads any skill found under `~/.claude/skills/`. The skill's **tool definitions** invoke the local CLI binary whenever you request AI media generation.

## Two Execution Paths: CLI vs. MCP

The `quickdesign` skill dynamically selects between two execution paths based on environment detection.

### CLI Path (Full Functionality)

When `quickdesign` binary is detected, the skill shells out to local commands. This supports all **25 tools** including paid generation and delivers the fastest, richest experience.

```bash

# Example: Generate a talking-avatar video via CLI path

quickdesign video generate \
  --provider seedance \
  --reference-image product.jpg \
  --reference-image avatar.jpg \
  --aspect-ratio 9:16 \
  --duration 12 \
  --resolution 1080p \
  -p '@Image2 says: "Check out product X!" No music score.' \
  -o seg1.mp4 \
  --wait

```

### MCP Path (Web Fallback)

If you're using `claude.ai` without the CLI installed, the skill falls back to `https://app.quickdesign.io/api/mcp`.

```bash

# Internal MCP call (web-only users)

curl -X POST https://app.quickdesign.io/api/mcp/video/generate \
  -H "Authorization: Bearer <OAuth-token>" \
  -d '{
    "provider": "seedance",
    "referenceImages": ["product.jpg"],
    "duration": 12,
    "resolution": "1080p"
  }'

```

**Limitation**: Paid generation remains CLI-only until the OAuth flow stabilizes. Cost queries and model lookup still work via MCP.

## Runtime Decision Logic in SKILL.md

The skill's environment detection logic, defined in [`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md) (lines 8-10) and detailed in [`references/connecting-claude-ai-via-mcp.md`](https://github.com/anthropics/claude-plugins-community/blob/main/references/connecting-claude-ai-via-mcp.md) (lines 70-78), follows this priority:

1. **Check for CLI binary** — If `quickdesign` is in `$PATH`, use CLI path
2. **Prompt for MCP connection** — If web-only, guide user through OAuth
3. **Suggest CLI install** — Recommend `quickdesign init` for full features

This automatic preference ensures power users get maximum capability without manual configuration.

## Runtime Model Discovery

Neither path hard-codes defaults. Both query the live model registry:

```bash

# List available video models

quickdesign video models

# Compute cost before generation

quickdesign cost seedance-2.0-r2v -d 12 -r 1080p

# → 250 cr (displayed in skill plan summary)

```

Per [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) (lines 52-60), the skill refreshes model and pricing data at invocation time.

## Key Source Files and Their Roles

| File | Purpose |
|------|---------|
| [`quickdesign/README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/README.md) | Installation guide describing both CLI and skill setup options |
| [`quickdesign/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json) | Plugin manifest enabling Claude Code recognition |
| [`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md) | Core skill definition with decision tree and tool schemas |
| [`quickdesign/skills/quickdesign/references/connecting-claude-ai-via-mcp.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/references/connecting-claude-ai-via-mcp.md) | MCP fallback mechanics and context detection logic |
| [`quickdesign/skills/quickdesign/models/seedance-2.0-r2v.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/models/seedance-2.0-r2v.md) | Default UGC/video model specification |

## Summary

- The **CLI handles all backend communication** with QuickDesign's MCP service—authentication, polling, and asset delivery
- **`quickdesign init` bridges CLI and Claude Code** by installing the skill to `~/.claude/skills/quickdesign/`
- The **skill automatically prefers the CLI path** when detected, falling back to MCP for web-only users
- **Runtime discovery** ensures model lists and pricing stay current—no hard-coded assumptions
- **Paid generation requires the CLI** for now; MCP path supports cost queries and model browsing only

## Frequently Asked Questions

### How do I know if the quickdesign skill is using my local CLI or the MCP fallback?

The skill checks for the `quickdesign` binary in your `$PATH` at runtime. If found, all operations execute via local CLI commands. If not found—common when using `claude.ai` in a browser—the skill transparently switches to MCP API calls against `app.quickdesign.io`. You'll see different tool availability: 25 tools with CLI versus a subset via MCP.

### Can I use the Claude Code skill without installing the quickdesign CLI?

Yes, but with reduced functionality. The MCP fallback supports model discovery, cost estimation, and browsing. However, **paid media generation currently requires the CLI** due to incomplete OAuth flows in the web path. Run `quickdesign init` on any machine where you need full generation capabilities.

### What happens when I run `quickdesign init`?

The command copies [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) and reference documentation from the package bundle into `~/.claude/skills/quickdesign/`. Claude Code automatically loads skills from this directory on startup. No additional configuration is needed—the skill immediately recognizes your CLI installation if present.

### Where does the skill store its decision logic for choosing CLI vs. MCP?

The primary logic resides in [`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md) (lines 8-10) with detailed fallback procedures in [`references/connecting-claude-ai-via-mcp.md`](https://github.com/anthropics/claude-plugins-community/blob/main/references/connecting-claude-ai-via-mcp.md) (lines 70-78). The skill implements a simple environment probe: binary presence test first, then conditional MCP routing based on user context.