What Is the Directory Structure for a Claude Plugin?

A Claude plugin follows a convention‑based layout anchored by a hidden .claude-plugin/ folder containing a required plugin.json manifest and a skills/ directory where each capability is defined in its own subfolder with a mandatory 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):

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 – The required manifest that declares the plugin’s name, version, description, and entry points for the skills. Located at .claude-plugin/plugin.json.
• 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 – Required in every skill folder (e.g., 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. 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 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 file.

4. Presentation – Optional UI assets such as icon.svg and 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:

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:

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 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 file describing inputs, outputs, and behavior.
• Optional assets: Supplementary folders like models/ and references/, along with icon.svg and 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 file. Claude registers each skill independently based on the entries declared in the root plugin.json manifest found in .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 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 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 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.

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