Directory Structure for an In-Repo Claude Plugin: Complete Guide

An in-repo Claude plugin requires a mandatory .claude-plugin/ folder containing plugin.json and marketplace.json, plus optional assets like icons, version files, and skill definitions, all organized as a self-contained sub-directory within the anthropics/claude-plugins-community repository.

The anthropics/claude-plugins-community repository hosts community-contributed Claude plugins that follow a strict conventional layout. Understanding the directory structure for an in-repo Claude plugin is essential for developers who want to contribute tools that Claude Code can discover, install, and execute without external packaging.

Required Directory Structure

Every in-repo Claude plugin lives as a top-level folder within the repository root. Claude Code scans these directories during marketplace addition to identify valid plugins.

The Root Plugin Folder

The plugin root uses a descriptive name (e.g., quickdesign/ or tres-finance-plugin/) and contains the implementation assets. According to the source analysis, the hierarchy looks like this:

<plugin-name>/
├─ .claude-plugin/                ← Required metadata container
│   ├─ plugin.json                 ← Core manifest (name, version, description)
│   ├─ marketplace.json            ← Marketplace entry (source path, strict flag)
│   ├─ icon.svg (optional)         ← 128 × 128 px UI icon
│   └─ .version (optional)         ← Version file for CLI checks
├─ skills/                         ← Optional skill definitions
├─ README.md                       ← Human-readable documentation
├─ LICENSE                         ← Open-source license
└─ .mcp.json (optional)            ← MCP-specific configuration

The .claude-plugin Metadata Container

The .claude-plugin/ directory is the critical discovery mechanism. Claude Code specifically looks for this hidden folder to identify the directory as a plugin rather than ordinary repository content. This folder must reside at the root of your plugin directory and contains the files that Claude Code reads to load and display the plugin in the marketplace.

Core Configuration Files

Two JSON files inside .claude-plugin/ are mandatory for the plugin to function.

plugin.json (Primary Manifest)

The plugin.json file declares the plugin identity and capabilities. As implemented in anthropics/claude-plugins-community, this file specifies the name, version, author, keywords, and user configuration options.

For example, the QuickDesign plugin declares its metadata in .claude-plugin/plugin.json:

{
  "name": "quickdesign",
  "version": "0.8.0",
  "description": "AI media generation skill for the QuickDesign CLI …",
  "author": { "name": "QuickDesign", "url": "https://quickdesign.io" },
  "keywords": ["ai","video-generation","image-generation","ugc"]
}

Claude Code reads this manifest to register the plugin under the specified name and make it available to the model.

marketplace.json (Marketplace Entry)

The marketplace.json file tells the Claude Code CLI where the plugin lives inside the repository and whether strict validation applies. This file enables the CLI to load the plugin without additional packaging steps by pointing to the current directory as the source.

Both the QuickDesign and tres-finance plugins include this file at .claude-plugin/marketplace.json, specifying "./" as the source path to indicate the plugin root is the current directory.

Optional Assets and Implementation

While the metadata files are mandatory, most functional plugins include additional directories and files that enhance usability.

Icons and Version Files

You may include an icon.svg file (128 × 128 pixels) inside .claude-plugin/ to display in the UI plugin picker. The QuickDesign plugin demonstrates this with .claude-plugin/icon.svg.

An optional .version file containing the version string (mirroring plugin.json) enables the CLI to perform quick version checks without parsing JSON. See .claude-plugin/.version in the QuickDesign folder for the implementation pattern.

skills/ Directory

The skills/ folder contains the actual implementation logic that Claude invokes. Each skill is defined in a Markdown file named SKILL.md. For example, the QuickDesign plugin stores its callable actions in skills/quickdesign/SKILL.md.

These skill definitions tell Claude what actions it can perform and how to execute them, effectively serving as the plugin's functional API.

Documentation and Licensing

Include a README.md at the plugin root for human-readable documentation and a LICENSE file specifying the open-source terms (MIT, Apache, etc.). While optional for technical operation, these files are required for community acceptance.

The optional .mcp.json file at the plugin root provides metadata for the internal "Claude Plugin Platform" (MCP) pipeline used by Anthropic tooling.

Discovery and Installation

Claude Code discovers in-repo plugins by scanning sub-directories for .claude-plugin/plugin.json when you add the community marketplace.

Add the marketplace and install a plugin using these commands:

# Add the community marketplace (once)

claude plugin marketplace add anthropics/claude-plugins-community

# Install the QuickDesign plugin from the repo

claude plugin install quickdesign@claude-community

# Verify installation

claude plugin list

The CLI uses the marketplace.json configuration to locate the plugin source at "./" (the current directory), allowing immediate loading without build steps or external packages.

Real-World Examples from the Repository

The anthropics/claude-plugins-community repository provides concrete implementations you can reference.

QuickDesign Plugin demonstrates the complete structure:

• Manifest: quickdesign/.claude-plugin/plugin.json
• Marketplace entry: quickdesign/.claude-plugin/marketplace.json
• UI icon: quickdesign/.claude-plugin/icon.svg
• Version tracking: quickdesign/.claude-plugin/.version

tres-finance-plugin follows the identical pattern:

• Manifest: tres-finance-plugin/.claude-plugin/plugin.json
• Marketplace entry: tres-finance-plugin/.claude-plugin/marketplace.json

Both plugins contain skills/ directories with multiple SKILL.md files that define Claude-callable actions, illustrating the typical implementation pattern for functional plugins.

Summary

• Mandatory structure: Every in-repo Claude plugin requires a top-level folder containing .claude-plugin/plugin.json and .claude-plugin/marketplace.json.
• Discovery mechanism: Claude Code scans for .claude-plugin/ folders when the marketplace is added via claude plugin marketplace add.
• Optional enhancements: Include icon.svg for UI display, .version for CLI version checking, and skills/ directories containing SKILL.md files for functionality.
• Documentation: Provide README.md and LICENSE files for community contribution standards.
• Source location: Reference existing plugins like quickdesign/ and tres-finance-plugin/ in the anthropics/claude-plugins-community repository for working examples.

Frequently Asked Questions

What happens if I forget to include the marketplace.json file?

Claude Code will fail to discover the plugin. The marketplace.json file is required because it tells the CLI that the plugin source lives in the current directory ("./") and specifies whether strict validation applies. Without this file, the plugin remains invisible to the installation command.

Can I use a PNG or JPG instead of SVG for the plugin icon?

No. According to the repository standards, the icon must be an SVG file named icon.svg with dimensions of 128 × 128 pixels. This vector format ensures the icon displays correctly at all resolutions in the Claude Code UI.

Do I need to create a separate repository for my Claude plugin?

No. An in-repo Claude plugin specifically lives as a sub-directory within the anthropics/claude-plugins-community repository. This centralized approach allows the community to contribute plugins through pull requests while letting users install them directly via the CLI without managing multiple git remotes.

What is the purpose of the .mcp.json file?

The .mcp.json file provides metadata for the internal "Claude Plugin Platform" (MCP) pipeline used by Anthropic's internal tooling. It is optional for community plugins and primarily used for internal processing and compatibility checks within the MCP ecosystem.

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