How to Understand the Sample Plugin Directory Structure in the Claude Plugins Community Repository

The Claude Plugins Community repository uses a canonical directory layout where each top-level plugin folder contains a .claude-plugin manifest subdirectory, documentation files, and a skills/ tree with SKILL.md definitions that Claude Code consumes at runtime.

The anthropics/claude-plugins-community repository hosts reference implementations for Claude Code and Claude Cowork extensions. Understanding the sample plugin directory structure enables developers to create compatible plugins, debug existing ones, and extend the ecosystem with new capabilities. The repository demonstrates this structure through three primary examples: quickdesign, testdino, and tres-finance-plugin.

The Manifest Layer: .claude-plugin/

Every plugin requires a .claude-plugin/ subdirectory that contains the metadata files Claude Code uses for registration and marketplace listing.

Inside quickdesign/.claude-plugin/, the plugin.json file defines the canonical name, version, author, description, and keywords for the runtime. Claude Code reads this file during the installation phase to register the plugin locally. The marketplace.json file serves as the entry point for the community marketplace index, providing the metadata required to display the plugin in searchable listings.

The testdino/.claude-plugin/plugin.json example demonstrates additional fields such as an email field for the author and configuration for remote MCP (Model Context Protocol) endpoints, while tres-finance-plugin/.claude-plugin/plugin.json shows how a single manifest can reference multiple bundled skills.

Documentation and Configuration Files

At the plugin root, standard open-source files provide human-readable context and legal clarity.

The README.md file contains installation instructions, usage notes, and quick-start guides that both developers and Claude agents consult. The LICENSE file provides SPDX-compatible licensing information required for distribution. Optionally, .mcp.json appears in plugins like quickdesign/ to expose remote tools and hosted APIs to Claude agents through the Model Context Protocol.

The Skills Bundle: skills/

The executable logic of a plugin resides in the skills/ directory, organized into subfolders named after individual skills.

Each skill folder contains a SKILL.md file that declares the skill's name, description, invocation triggers, and the Bash commands the Claude Code runtime executes. For example, quickdesign/skills/quickdesign/SKILL.md defines the video generation workflow.

Supporting subdirectories enhance skill functionality:

• references/: Holds best-practice documentation such as quickdesign/skills/quickdesign/references/voice-continuity.md and multi-reference-pattern.md, which agents read to enforce rules during execution.
• pipelines/: Contains multi-step workflow definitions like ugc-video.md that chain multiple CLI calls together.
• models/: Stores per-model "cards" such as seedance-2.0-r2v.md that document model-specific flags, prompt skeletons, and cost parameters.

The tres-finance-plugin demonstrates bundling multiple distinct skills by placing tres-wallets-upload/ and other skill folders under its skills/ directory.

Runtime Integration and Execution Flow

Understanding how Claude Code consumes these files clarifies the directory structure's purpose.

Marketplace discovery relies on the root-level README.md and marketplace.json files to populate the installable plugin list. During installation, running /plugin install quickdesign@quickdesign copies the entire quickdesign/.claude-plugin folder into ~/.claude/plugins/quickdesign/ and registers the skill defined in skills/quickdesign/SKILL.md.

At execution time, Claude evaluates the when to invoke section of SKILL.md to determine trigger conditions, then runs the specified Bash snippets. For MCP integration, plugins like testdino establish secure connections to remote endpoints defined in their manifest, exposing remote tools as if they were local commands without requiring local binaries.

Practical Code Examples

Install a sample plugin from the community marketplace:

# Inside Claude Code chat

/plugin marketplace add anthropics/claude-plugins-community
/plugin install quickdesign@quickdesign

Invoke a local skill with specific model parameters:

# Claude-generated command based on SKILL.md definition

quickdesign video generate \
  --provider seedance \
  --reference-image product.jpg \
  --reference-image avatar.jpg \
  --aspect-ratio 9:16 --duration 12 --resolution 1080p \
  -p '@Image2 talks to @Image1. "Check out this new product!" No music score. No subtitles.' \
  -o promo.mp4 --wait

Query a remote MCP plugin without local installation:

# Claude translates this into an HTTP call against the configured endpoint

Use the TestDino connector. Call health and tell me which projects I have access to.

Add a new skill to an existing plugin by creating the proper file structure:

# File: quickdesign/skills/quickdesign/new-feature/SKILL.md

---
name: quickdesign-new-feature
description: |
  Chains subtitle generation after video creation.
---
quickdesign video generate ... -o raw.mp4 --wait
quickdesign video subtitle raw.mp4 -o final.mp4 --wait

After committing, reinstall with /plugin install quickdesign@quickdesign to register the new skill automatically.

Summary

• Top-level isolation: Each plugin resides in its own folder (e.g., quickdesign/, testdino/) to prevent file conflicts.
• Manifest requirement: The .claude-plugin/plugin.json file is mandatory for runtime registration and marketplace listing.
• Executable skills: The skills/<skill-name>/SKILL.md pattern defines what Claude executes and when.
• Support directories: references/, pipelines/, and models/ folders provide context, workflows, and model-specific configuration.
• MCP support: The optional .mcp.json enables remote tool integration without local binaries.

Frequently Asked Questions

What information does plugin.json contain?

The plugin.json file specifies the plugin's canonical name, version, author contact information, description, and keywords. According to the quickdesign source, this manifest resides at .claude-plugin/plugin.json and serves as the single source of truth for the Claude Code plugin manager during registration.

How does Claude Code determine when to run a skill?

Claude evaluates the when to invoke section defined in each SKILL.md file located under skills/<name>/. This declarative section contains natural language conditions that trigger the skill, followed by the Bash commands specified in the same file that Claude executes in the user's environment.

What is the difference between local and MCP-based plugins?

Local plugins like quickdesign ship executable binaries or scripts that run directly on the user's machine, defined in SKILL.md Bash sections. MCP-based plugins like testdino define remote endpoints in their manifest; Claude Code connects to these servers via HTTP, authenticates via OAuth, and exposes the remote tools without requiring local installation of the tool itself.

Can a single plugin contain multiple skills?

Yes. The tres-finance-plugin demonstrates this pattern by placing multiple skill subdirectories under its skills/ folder, such as skills/tres-wallets-upload/. Each subdirectory contains its own SKILL.md, allowing one plugin to bundle related but distinct capabilities under a single .claude-plugin manifest.

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