Directory Structure for In-Repo Claude Plugins: Complete Guide

Every in-repo Claude plugin lives in a top-level folder with a mandatory .claude-plugin/ subdirectory containing plugin.json and marketplace.json manifests.

The anthropics/claude-plugins-community repository demonstrates a standardized layout that enables automatic discovery and loading by the Claude Plugin Marketplace (MCP). Understanding this directory structure is essential for contributors building new plugins or integrating existing ones into Claude workflows.

Standard Plugin Layout

Each plugin follows a consistent skeleton across the repository:

<plugin-name>/
├─ .claude-plugin/
│   ├─ plugin.json          # Core manifest: name, version, entry points, skills

│   ├─ marketplace.json     # UI metadata: tags, description, icons

│   └─ [optional assets]    # e.g., icon.svg for marketplace display

├─ README.md                # Human-readable documentation

├─ LICENSE                  # License file

└─ [plugin-specific files]  # Skills, scripts, tests, and assets

This uniformity allows the MCP to scan, validate, and deploy plugins without manual configuration.

The .claude-plugin/ Directory Explained

The hidden .claude-plugin/ folder serves as the MCP entry point for every in-repo plugin.

plugin.json – Core Manifest

This required file declares:

• Plugin identity – name, version, author
• Runtime requirements – compatible Claude versions
• Skills list – the functional units Claude uses to generate actions

marketplace.json – UI Metadata

This optional but recommended file supplies:

• Display tags for marketplace categorization
• Short summary text for the Claude UI
• Icon references for visual identification

Optional Assets

Additional files like icon.svg enhance marketplace presentation. The quickdesign plugin includes this at quickdesign/.claude-plugin/icon.svg.

Current In-Repo Plugins

The claude-plugins-community repository contains four reference implementations:

Plugin	Purpose	Key Files
tres-finance-plugin	Finance helpers: ledger linking, invoice matching	.claude-plugin/plugin.json • .claude-plugin/marketplace.json
testdino	Testing utilities: session tracking, run management	.claude-plugin/plugin.json • .claude-plugin/marketplace.json
quickdesign	Video-design assistance: reference handling, pipelines	.claude-plugin/plugin.json • .claude-plugin/marketplace.json • .claude-plugin/icon.svg
eli5	Concept simplification: "Explain-It-Like-I'm-5"	.claude-plugin/plugin.json • .claude-plugin/marketplace.json

All four plugins follow the identical directory structure for in-repo Claude plugins, enabling consistent tooling and validation.

Skill Files Location

Functional capabilities reside in plugin-specific skills/ directories. For example, tres-finance-plugin/skills/ contains Markdown-based SKILL definitions that Claude interprets to generate actions. These skill files expand the manifest's skills list into executable behavior.

Automated Validation

The repository's validation CI (.github/workflows/validate-plugins.yml) automatically scans this directory structure for in-repo Claude plugins. The workflow verifies that:

• .claude-plugin/plugin.json exists and is valid JSON
• Required fields (name, version, skills) are present
• Marketplace metadata is well-formed when provided

This automation depends on the strict layout consistency across all plugins.

Working with Plugin Manifests Programmatically

Access manifest data using standard file operations:

import json
from pathlib import Path

def load_plugin_manifest(plugin_dir: Path) -> dict:
    """Load the plugin.json of an in-repo plugin."""
    manifest_path = plugin_dir / ".claude-plugin" / "plugin.json"
    with manifest_path.open() as f:
        return json.load(f)

# Example: load the quickdesign plugin manifest

quickdesign = load_plugin_manifest(Path("quickdesign"))
print(quickdesign["name"], quickdesign["version"])

This pattern extracts version information, skill lists, or author details for tooling and documentation generation.

Summary

• Top-level folders isolate each plugin in the repository root
• .claude-plugin/ contains required manifests and optional UI assets
• plugin.json defines runtime behavior and skill registration
• marketplace.json controls Claude UI presentation
• README.md and LICENSE complete the standard documentation set
• Validation CI enforces structural correctness automatically

Frequently Asked Questions

What happens if plugin.json is missing from .claude-plugin/?

The plugin will fail validation. The MCP requires plugin.json as the authoritative source for plugin identity, version, and skill definitions. The CI workflow .github/workflows/validate-plugins.yml will reject any plugin directory lacking this file.

Can I include additional files in .claude-plugin/ beyond the standard manifests?

Yes. The directory structure for in-repo Claude plugins permits optional assets like icon.svg, as demonstrated by quickdesign/.claude-plugin/icon.svg. These files enhance marketplace presentation without affecting core functionality.

How does the MCP discover plugins in a large repository?

The MCP scans top-level directories and checks for the presence of .claude-plugin/plugin.json. This predictable pattern eliminates the need for a central registry—each plugin is self-describing through its manifest files.

Where should skill definitions be stored relative to the manifest?

Skill definitions typically reside in a skills/ subdirectory within the plugin folder (e.g., tres-finance-plugin/skills/). The manifest's skills array references these files, creating the connection between declaration and implementation.

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