# Repository Architecture for Claude-Plugins-Community: A Complete Technical Guide

> Explore the claude-plugins-community repository architecture. Learn how community Claude plugins are organized with metadata descriptors and CI validation for schema compliance.

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

---

**The claude-plugins-community repository is a read-only mirror that organizes community Claude plugins into flat subdirectories anchored by a central [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file, with each plugin containing its own metadata descriptors and CI pipelines validating manifest schema compliance.**

The claude-plugins-community repository serves as the official marketplace for community-contributed Claude plugins. Understanding the repository architecture for claude-plugins-community is essential for developers who want to integrate these extensions into Claude Code or Claude Cowork workflows. This guide breaks down the directory structure, metadata files, and validation systems that power this ecosystem.

## High-Level Directory Structure

The repository follows a flat organizational pattern where each plugin occupies its own top-level directory. This design scales horizontally while maintaining strict separation between plugin code and marketplace metadata.

### Root Marketplace Catalog

The [`/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main//.claude-plugin/marketplace.json) file acts as the single source of truth for all installable plugins. According to the anthropics/claude-plugins-community source code, this JSON array enumerates every community plugin with fields including `name`, `description`, `source`, and optional `homepage`. The `source` field can reference external repository URLs, Git subdirectories, or specific commit SHAs that Claude Cowork resolves during installation.

### Plugin Directories

Each plugin lives in its own folder (e.g., `tres-finance-plugin/`, `testdino/`, `quickdesign/`, `eli5/`). Inside every plugin directory, the [`/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main//.claude-plugin/plugin.json) file defines runtime metadata such as version, author, configuration schema, and licensing. Some plugins also include an optional [`/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main//.claude-plugin/marketplace.json) for local testing before submission to the central catalog.

### CI/CD and Validation Pipelines

The `/.github/workflows/` directory contains automated pipelines that enforce repository standards. The [`validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/validate-plugins.yml) workflow executes on every push to verify manifest schema compliance, check for required fields, and prevent duplicate SHAs. The [`owner-liveness-sweep.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/owner-liveness-sweep.yml) workflow periodically verifies plugin ownership to maintain catalog accuracy.

## Key Metadata Files Explained

Understanding the distinction between the two JSON formats prevents configuration errors during plugin development.

### plugin.json vs marketplace.json

The [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) file located at `/<plugin-name>/.claude-plugin/plugin.json` contains the runtime configuration schema. For example, the TRES Finance plugin specifies sensitive API key requirements in its `userConfig` object, prompting Claude Code to request credentials before executing finance-related skills.

The [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) files exist at both the root ([`/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main//.claude-plugin/marketplace.json)) and optionally within individual plugin directories. While the root catalog serves the global marketplace, per-plugin [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) files enable developers to test installations locally without publishing to the central repository.

## How Plugin Discovery Works

Claude Cowork and Claude Code consume the root [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) when you register the community source. The CLI reads the catalog, resolves the `source` URL for your selected plugin, clones the indicated repository at the pinned SHA, and registers the plugin's MCP tools automatically.

## Installing and Configuring Community Plugins

To add plugins from this repository to your Claude environment, first register the marketplace source, then install specific plugins by name.

```bash

# Add the community marketplace (only needed once)

claude plugin marketplace add anthropics/claude-plugins-community

# Install a specific plugin, e.g., the TRES Finance plugin

claude plugin install tres-finance-plugin@claude-community

```

The system resolves the plugin's source URL from the marketplace metadata and handles dependency resolution automatically.

Plugin configurations follow the schema defined in each [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json). The TRES Finance plugin, for instance, requires a DeBank API key:

```json
{
  "name": "tres-finance-plugin",
  "version": "1.12.1",
  "userConfig": {
    "DEBANK_API_KEY": {
      "title": "DeBank API Key",
      "description": "Your DeBank Pro API key for balance validation",
      "type": "string",
      "sensitive": true
    }
  }
}

```

The `"sensitive": true` flag ensures Claude Code masks this value during input and storage.

## Validating Plugin Manifests Locally

Before submitting plugins to the internal review pipeline, developers can validate their manifests using the repository's CI scripts.

To verify a new skill addition, ensure your files are correctly referenced in [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json), then run the detection script:

```bash

# From the repo root

bash .github/actions/validate-plugins/scripts/00-detect-changes.sh

```

For full marketplace validation, execute:

```bash
bash .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh

```

This script parses [`/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main//.claude-plugin/marketplace.json), validates JSON schema compliance for each entry, and reports violations. Successful execution confirms your plugin is ready for the production marketplace.

When adding documentation skills, place markdown files in the appropriate subdirectory. For example, the quickdesign plugin stores brand guidelines at [`quickdesign/skills/quickdesign/references/brand-and-moderation.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/references/brand-and-moderation.md):

```markdown

# File: quickdesign/skills/quickdesign/references/brand-and-moderation.md

## Brand & Moderation Guidelines

- Do not generate content that violates platform policies.
- Respect trademarked names and copyright.
- Prompt the user for clarification when brand-specific tone is required.

```

## Summary

- The **root marketplace.json** ([`/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main//.claude-plugin/marketplace.json)) serves as the canonical catalog consumed by Claude tools during plugin discovery.
- Each plugin directory contains a **plugin.json** defining runtime metadata, configuration schemas, and version information.
- **GitHub Actions workflows** in `/.github/workflows/` automatically validate manifest syntax and enforce naming conventions on every commit.
- The repository operates as a **read-only mirror**, meaning direct pull requests are automatically closed; new plugins enter through Anthropic's internal review pipeline.
- Local validation scripts in `.github/actions/validate-plugins/scripts/` enable pre-submission testing of marketplace entries.

## Frequently Asked Questions

### What is the purpose of the root marketplace.json file?

The [`/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main//.claude-plugin/marketplace.json) file functions as the central registry that Claude Cowork and Claude Code query when you run `claude plugin marketplace add`. It contains an array of plugin objects with metadata including source URLs, descriptions, and version pins, enabling the CLI to resolve and install community extensions automatically.

### How do I add a new plugin to the claude-plugins-community repository?

Because this repository is a read-only mirror from an internal Anthropic pipeline, you cannot submit plugins via direct pull request. Instead, new plugins must flow through Anthropic's internal review process. Once approved, the system automatically mirrors your plugin into the appropriate `/<plugin-name>/` directory with its [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) metadata.

### What validation checks run against plugins in the CI pipeline?

The [`/.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main//.github/workflows/validate-plugins.yml) workflow executes several validation steps: it verifies each plugin's manifest conforms to the required JSON schema, checks that mandatory fields (name, version, source) are present, ensures no duplicate commit SHAs exist in the marketplace, and validates that plugin structures match their declared metadata.

### Is the claude-plugins-community repository open to direct contributions?

No. While the repository uses an MIT license and its contents are publicly readable, it functions strictly as a stable, version-controlled snapshot. Direct pull requests are closed automatically by repository policies. Users should treat this as a consumption endpoint rather than a contribution target, though they can reference the architecture when building their own plugin distributions.