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

The claude-plugins-community repository is a read-only mirror that organizes community Claude plugins into flat subdirectories anchored by a central 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 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 file defines runtime metadata such as version, author, configuration schema, and licensing. Some plugins also include an optional /.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 workflow executes on every push to verify manifest schema compliance, check for required fields, and prevent duplicate SHAs. The 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 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 files exist at both the root (/.claude-plugin/marketplace.json) and optionally within individual plugin directories. While the root catalog serves the global marketplace, per-plugin 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 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.

# 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. The TRES Finance plugin, for instance, requires a DeBank API key:

{
  "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, then run the detection script:

# From the repo root

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

For full marketplace validation, execute:

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

This script parses /.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:

# 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) 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 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 metadata.

What validation checks run against plugins in the CI pipeline?

The /.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.

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