# Directory Structure for In-Repo Claude Plugins: Complete Guide

> Learn the directory structure for in-repo Claude plugins. Discover how to organize your plugin files with the essential .claude-plugin subdirectory and manifest files.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-05

---

**Every in-repo Claude plugin lives in a top-level folder with a mandatory `.claude-plugin/` subdirectory containing [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) and [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) • [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) |
| **testdino** | Testing utilities: session tracking, run management | [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) • [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) |
| **quickdesign** | Video-design assistance: reference handling, pipelines | [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) • [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) • `.claude-plugin/icon.svg` |
| **eli5** | Concept simplification: "Explain-It-Like-I'm-5" | [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) • [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml)) automatically scans this directory structure for in-repo Claude plugins. The workflow verifies that:

- [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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:

```python
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`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)** defines runtime behavior and skill registration
- **[`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json)** controls Claude UI presentation
- **[`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md) and `LICENSE`** complete the standard documentation set
- **Validation CI** enforces structural correctness automatically

## Frequently Asked Questions

### What happens if [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) is missing from `.claude-plugin/`?

The plugin will fail validation. The MCP requires [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) as the authoritative source for plugin identity, version, and skill definitions. The CI workflow [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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.