# What Is the Directory Structure for a Claude Plugin?

> Discover the directory structure for a Claude plugin. Learn about the .claude-plugin folder, plugin.json manifest, and skills directory for defining capabilities.

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

---

**A Claude plugin follows a convention‑based layout anchored by a hidden `.claude-plugin/` folder containing a required [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest and a `skills/` directory where each capability is defined in its own subfolder with a mandatory [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file.**

The `anthropics/claude-plugins-community` repository establishes the canonical blueprint that Claude AI uses to discover, parse, and execute third‑party plugins. Understanding the directory structure for a Claude plugin ensures your code is automatically recognizable by the Claude runtime and properly displayed in the marketplace.

## The Standard Claude Plugin Directory Layout

According to the source code in `anthropics/claude-plugins-community`, a fully functional plugin follows this hierarchical pattern (illustrated using the **quickdesign** plugin):

```text
quickdesign/                     ← Root of the plugin
├─ .claude-plugin/               ← Plugin metadata (hidden)
│   ├─ plugin.json               ← Core manifest (required)
│   ├─ marketplace.json          ← Marketplace metadata (optional)
│   └─ icon.svg                  ← Plugin icon (optional)
├─ skills/                       ← Collection of skills
│   └─ quickdesign/              ← One skill package
│       ├─ SKILL.md              ← Skill definition (required)
│       ├─ models/               ← Model‑specific assets (optional)
│       │   ├─ topaz-video-upscale.md
│       │   └─ sora2-i2v.md
│       └─ references/           ← Supporting docs (optional)
│           ├─ voice-continuity.md
│           └─ ...                ← Additional reference files
├─ README.md                     ← Human‑readable overview
└─ LICENSE                       ← License file

```

## Core Components and File Locations

### The .claude-plugin/ Metadata Folder

The hidden `.claude-plugin/` directory resides at the repository root and stores the plugin’s identity and marketplace configuration.

- **[`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)** – The required manifest that declares the plugin’s name, version, description, and entry points for the skills. Located at [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json).
- **[`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json)** – Optional metadata for the Claude marketplace, including pricing, tags, and categorization.
- **`icon.svg`** – Optional SVG asset that represents the plugin in the Claude UI.

### The skills/ Directory Structure

All functional capabilities live under the `skills/` folder (or a similarly named folder), with each skill isolated in its own subdirectory.

- **[`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md)** – Required in every skill folder (e.g., [`skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/skills/quickdesign/SKILL.md)). This markdown file defines the skill’s behavior, input schema, output types, usage examples, and runtime scripts.
- **`models/`** – Optional subdirectory for model‑specific prompts or configuration files.
- **`references/`** – Optional folder containing supporting documentation referenced by the skill.

## How Claude Discovers and Loads Plugin Contents

The Claude runtime processes the directory structure through four distinct phases:

1. **Discovery** – Claude scans the `.claude-plugin` folder for [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json). This file provides the plugin’s unique identifier and the list of skill entry points.

2. **Skill Registration** – For each skill declared in the manifest, Claude locates a sibling folder under `skills/` containing a [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file. The system parses this markdown to extract the skill’s schema, including input types, output types, and sample calls.

3. **Runtime Assets** – When a skill executes, Claude loads supplemental resources from predictable subfolders (`models/`, `references/`, or `scripts/`) placed alongside the [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file.

4. **Presentation** – Optional UI assets such as `icon.svg` and [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) enable the Claude interface to render the plugin correctly in the marketplace and settings panels.

## Programmatically Accessing Plugin Files

When automating deployments or validating plugin integrity, you can interact with the directory structure programmatically. The following Python snippet demonstrates how to load the core manifest and enumerate skills from a locally cloned repository:

```python
import json
from pathlib import Path

# Load the core manifest

plugin_root = Path("quickdesign")
manifest_path = plugin_root / ".claude-plugin" / "plugin.json"
with manifest_path.open() as f:
    manifest = json.load(f)

print(f"Plugin name: {manifest['name']}")
print(f"Version: {manifest['version']}")

# List all defined skills

skills_dir = plugin_root / "skills"
skill_names = [p.name for p in skills_dir.iterdir() if p.is_dir()]
print("Available skills:", skill_names)

# Read a specific skill definition

skill_path = skills_dir / "quickdesign" / "SKILL.md"
skill_md = skill_path.read_text()
print("\n--- SKILL.md preview ---")
print(skill_md[:200])  # Show first 200 characters

```

Running this script against the `quickdesign` plugin yields:

```text
Plugin name: quickdesign
Version: 1.0.0
Available skills: ['quickdesign']
--- SKILL.md preview ---

# QuickDesign Skill

...

```

## Summary

- **Root metadata**: Every plugin must contain a `.claude-plugin/` folder with a required [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest file.
- **Skill organization**: Functional code and definitions reside in `skills/<skill-name>/` subdirectories.
- **Required skill file**: Each skill folder must include a [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file describing inputs, outputs, and behavior.
- **Optional assets**: Supplementary folders like `models/` and `references/`, along with `icon.svg` and [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json), enhance functionality and presentation but are not mandatory.

## Frequently Asked Questions

### Can a Claude plugin contain multiple skills?

Yes. The `skills/` directory supports multiple subdirectories, each representing a distinct capability with its own [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file. Claude registers each skill independently based on the entries declared in the root [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest found in [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json).

### Is the .claude-plugin folder required for all Claude plugins?

Yes. The hidden `.claude-plugin` directory is mandatory because it houses the [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) file that declares the plugin’s unique identifier, version, and skill entry points. Without this folder and its core manifest, the Claude runtime cannot discover or load the plugin.

### What is the purpose of the SKILL.md file?

The [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file serves as the formal contract between the developer and Claude’s execution environment. It specifies the skill’s name, input schema, output types, usage examples, and any runtime scripts required for the skill to operate correctly.

### Are the models/ and references/ subfolders required in every skill?

No. While the [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file is required within each skill directory, subfolders such as `models/` for model‑specific prompts and `references/` for supporting documentation are optional. Include them only when your skill requires supplemental resources beyond the core skill definition.