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

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.

# Installs SKILL.md and reference docs to Claude Code

quickdesign init

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

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

# 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 (lines 8-10) and detailed in 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:

# 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 (lines 52-60), the skill refreshes model and pricing data at invocation time.

Key Source Files and Their Roles

File	Purpose
quickdesign/README.md	Installation guide describing both CLI and skill setup options
quickdesign/.claude-plugin/plugin.json	Plugin manifest enabling Claude Code recognition
quickdesign/skills/quickdesign/SKILL.md	Core skill definition with decision tree and tool schemas
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	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 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 (lines 8-10) with detailed fallback procedures in 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.

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