# How Is the claude-plugins-community Repository Structured? A Complete Technical Guide

> Understand the claude-plugins-community repository structure. Explore its two-tier architecture, marketplace.json, and individual plugin directories for a complete technical overview.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: technical-guide
- Published: 2026-08-24

---

**The claude-plugins-community repository employs a two-tier architecture: a top-level [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file indexes every community plugin, while each plugin resides in its own subdirectory containing a local manifest, documentation, and runtime assets.**

The claude-plugins-community repository functions as a read-only mirror of Anthropic's community plugin marketplace, standardizing how Claude Code discovers and loads third-party skills. Understanding the claude-plugins-community repository structure allows developers to contribute new plugins, troubleshoot installations, and programmatically interact with the marketplace index.

## Top-Level Directory Layout

The repository root separates global marketplace metadata from individual plugin bundles and continuous integration logic.

```

claude-plugins-community/
│
├─ .claude-plugin/                # Marketplace-level metadata

│   └─ marketplace.json          # Canonical index of all plugins

│
├─ .github/                       # Automation and validation

│   ├─ workflows/                 # GitHub Actions definitions

│   │   └─ validate-plugins.yml  # Manifest validation pipeline

│   └─ actions/                   # Reusable workflow components

│
├─ <plugin-name>/                 # Individual plugin directories

│   ├─ .claude-plugin/            # Plugin-specific configuration

│   ├─ SKILL.md                   # Human-readable documentation

│   └─ ...                        # Implementation assets

│
├─ README.md                      # Repository documentation

└─ LICENSE                        # SPDX-compatible license file

```

The [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) file serves as the single source of truth, enumerating every available plugin with fields for `name`, `source` URL, Git `sha`, `homepage`, and optional user configuration definitions. Claude Code reads this file first when resolving plugin installation requests.

## Per-Plugin Bundle Structure

Each community plugin occupies its own top-level directory (for example, `tres-finance-plugin/`, `testdino/`, `quickdesign/`, or `eli5/`). These bundles are self-contained and portable.

Inside every plugin folder, you will find:

- **[`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json)** – The plugin manifest that specifies the plugin name, version, author metadata, expected user configuration, and MCP (Model Context Protocol) server endpoint details. This file tells Claude Code how to initialize and communicate with the skill.
- **[`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md)** – A markdown file rendered directly in the Claude UI when users invoke help commands (for example, `/quickdesign help`). It describes the plugin's capabilities, command syntax, and usage examples.
- **Runtime assets** – Scripts, model files, or reference documentation required for the plugin to function, all co-located within the bundle.

This isolation ensures that installing `tres-finance-plugin@claude-community` pulls only the files relevant to that specific skill, without cross-contamination from other community contributions.

## CI/CD and Validation Workflows

The `.github/workflows/` directory houses automation that maintains repository integrity. The primary workflow, [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml), executes on every commit to verify:

- Every plugin listed in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) has a corresponding directory and valid [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest.
- Required fields (name, version, author, configuration schema) are present and correctly typed.
- The Git SHA referenced in the marketplace entry points to an existing, valid commit.
- No drift exists between the marketplace index and the actual file system layout.

These checks ensure that Claude Code can reliably resolve plugins without encountering broken manifests or missing dependencies.

## How Claude Code Consumes the Repository

The resolution flow follows a strict hierarchy:

1. **Discovery** – Claude Code fetches [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) from the repository root.
2. **Resolution** – When a user runs `claude plugin install <plugin-name>@claude-community`, the system looks up the entry by name, verifying the source URL and pinned SHA.
3. **Loading** – The local [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) within the plugin's subdirectory is parsed to determine initialization parameters and MCP endpoint configuration.
4. **Presentation** – The [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file is rendered in the UI to guide the user on available commands and capabilities.
5. **Execution** – Any bundled scripts or assets referenced in the manifest are loaded into the execution environment.

This pipeline guarantees that the claude-plugins-community repository structure remains both human-readable and machine-parseable.

## Programmatically Interacting with the Structure

You can interact with the repository layout directly using standard HTTP requests or local file system operations.

### Listing All Community Plugins

This Python script consumes the same marketplace index used by Claude Code:

```python
import json
import urllib.request

url = "https://raw.githubusercontent.com/anthropics/claude-plugins-community/main/.claude-plugin/marketplace.json"

with urllib.request.urlopen(url) as response:
    marketplace = json.load(response)

for plugin in marketplace["plugins"]:
    print(f"- {plugin['name']}: {plugin['description']}")

```

### Resolving a Plugin Manifest Locally

To access a specific plugin's configuration programmatically:

```python
import json
import pathlib

def load_plugin_manifest(plugin_name: str) -> dict:
    """
    Load the plugin.json for a given plugin directory.
    Assumes execution from repository root.
    """
    manifest_path = pathlib.Path(plugin_name) / ".claude-plugin" / "plugin.json"
    return json.loads(manifest_path.read_text())

# Example usage

manifest = load_plugin_manifest("tres-finance-plugin")
print(f"Version: {manifest['version']}, Author: {manifest['author']['name']}")

```

### Displaying Plugin Documentation

To view the human-readable skill description for a plugin like `quickdesign`:

```bash
cat quickdesign/skills/quickdesign/SKILL.md

```

This outputs the markdown content that appears in the Claude UI, identical to what users see when requesting help within the application.

## Summary

- The **[`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)** file at the repository root provides the canonical index of all available plugins, linking names to specific Git SHAs.
- Each plugin lives in its own directory containing **[`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json)** for machine configuration and **[`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md)** for human documentation.
- The **[`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml)** pipeline enforces schema consistency between the marketplace index and individual plugin manifests.
- The structure supports portability: every plugin bundle is self-contained, bundling its own manifest, documentation, and runtime assets.
- Claude Code resolves plugins by walking from the global marketplace index down to the local plugin manifest before rendering documentation in the UI.

## Frequently Asked Questions

### What is the difference between marketplace.json and plugin.json?

The [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) file is the global registry listing every plugin available in the community, including their source locations and version SHAs. In contrast, each plugin's local [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) contains the specific runtime configuration, author details, and MCP server settings required for that individual skill to execute.

### How does Claude Code locate a plugin's user documentation?

After resolving a plugin through the marketplace index, Claude Code looks for a [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file in the plugin's root directory. This markdown file is rendered directly in the chat interface when users invoke help commands, providing syntax guides and capability descriptions without requiring additional API calls.

### What validation ensures plugin integrity?

The [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) GitHub Action runs on every pull request and push, verifying that all marketplace entries have corresponding directories, that every [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) contains required fields (name, version, author), and that referenced Git SHAs exist in the repository history. This prevents broken or incomplete plugins from reaching the main branch.

### Can I contribute a new plugin to this repository?

Yes, the repository accepts community contributions following the established directory conventions. New submissions must include a unique top-level directory, a valid [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) manifest, a descriptive [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file, and pass the automated validation workflow before being added to [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json).