# How to Test Claude Plugins Locally: A Complete Development Guide

> Learn to test Claude plugins locally with our complete guide. Validate your manifest and load plugins directly in Claude Code for seamless development.

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

---

**To test Claude plugins locally, use `claude plugin validate` to check your manifest, then load the plugin with `claude --plugin-dir ./folder` to interact with skills directly in Claude Code.**

Testing Claude plugins locally allows you to validate manifests, debug MCP tool integrations, and verify user configuration flows before submitting to the marketplace. The `anthropics/claude-plugins-community` repository provides the validation scripts and CLI commands needed to replicate the entire CI pipeline on your machine. This guide covers the exact steps to validate, load, and exercise plugins using the same checks that run in GitHub Actions.

## Local Plugin Architecture

Claude plugins follow a standardized directory structure that the CLI recognizes when loading from the filesystem.

### The .claude-plugin Directory Structure

Every plugin resides in a folder containing a `.claude-plugin/` subdirectory. This directory houses the core metadata and configuration files required by the Claude Code CLI. According to the repository structure demonstrated in [`tres-finance-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json), the manifest defines the plugin's skills, user-configurable parameters, and MCP server connections.

### Manifest and Configuration Files

The **[`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)** file contains the essential metadata, skill definitions, and `userConfig` schema for sensitive values like API keys. An optional **[`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json)** file provides marketplace-specific listing details. When you test Claude plugins locally, the CLI reads these files to determine available skills and prompt for any required configuration values.

## Validating Plugin Manifests Locally

Before loading a plugin into Claude Code, you must ensure the manifest passes schema validation. The repository's CI pipeline runs these same checks automatically, but you can execute them manually during development.

### Running Static Validation Checks

The `claude plugin validate` command performs the same static analysis used by the GitHub Actions workflow. This validates JSON schema compliance, skill definitions, and required fields.

```bash
claude plugin validate tres-finance-plugin/.claude-plugin/plugin.json

```

A successful validation returns "OK", while failures provide detailed error output indicating which schema requirements are unmet. This command replicates the logic found in [`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh), specifically the `cli_validate` function used by the CI pipeline.

## Loading and Testing Plugins in Claude Code

Once validation passes, you can load the plugin directly into an interactive Claude Code session or invoke specific skills via the command line.

### Interactive Testing with --plugin-dir

Use the `--plugin-dir` flag to tell the Claude Code CLI to include your local plugin folder in its search path. This bypasses the marketplace and makes all skills defined under the `skills/` directory immediately available.

```bash
cd tres-finance-plugin
claude --plugin-dir .

```

When the session starts, Claude Code recognizes every skill defined in your manifest. You can then test functionality naturally by asking Claude to run specific skills, such as "run tres-asset-balance-validation for wallet 0x123...".

### Invoking Skills via CLI

For automated testing or debugging without the interactive UI, use the `claude plugin run` command to execute specific skills directly from the terminal. This approach is useful for CI/CD pipelines or rapid iteration on individual tools.

```bash
claude plugin run tres-asset-balance-validation \
    wallet="0xDEADBEEF0123456789abcdef" \
    network="ethereum"

```

This command invokes the skill against the real or mock MCP server defined in your plugin configuration, returning results directly to the terminal output.

## Handling User Configuration and API Keys

Many plugins require sensitive configuration values such as API keys or authentication tokens. The `userConfig` section in [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) declares these requirements, and the CLI handles them securely during local testing.

When loading a plugin locally, Claude Code prompts you to enter any required configuration values. Alternatively, create a temporary `.env` file in the plugin directory to pre-populate these values during testing:

```bash
echo "DEBANK_API_KEY=your-key-here" > .env

```

This approach allows you to test Claude plugins locally without hardcoding credentials into the manifest or committing them to version control.

## Reproducing CI Validation Locally

To ensure your plugin passes the automated checks run on pull requests, you can execute the exact same validation scripts used by GitHub Actions. The repository stores these utilities in `.github/actions/validate-plugins/scripts/`.

Run the full validation suite locally:

```bash

# From the repository root

bash .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh
bash .github/actions/validate-plugins/scripts/30-validate-cli-external.sh
bash .github/actions/validate-plugins/scripts/40-validate-cli-local.sh

```

These scripts validate marketplace entries, external plugins, and local plugin folders respectively, using the same `cli_validate` helper defined in [`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh). Running these locally ensures your changes will pass the repository's quality gates before you open a pull request.

## Summary

- **Validate manifests** using `claude plugin validate <path>` to catch schema errors before runtime.
- **Load plugins interactively** with `claude --plugin-dir ./folder` to test skills within Claude Code conversations.
- **Automate skill testing** via `claude plugin run <skill-name>` for headless validation and debugging.
- **Manage secrets** through the `userConfig` schema and temporary `.env` files during local development.
- **Reproduce CI checks** by executing the bash scripts in `.github/actions/validate-plugins/scripts/` to ensure compliance with repository standards.

## Frequently Asked Questions

### How do I validate the plugin.json syntax before testing?

Run `claude plugin validate .claude-plugin/plugin.json` from your plugin directory. This command checks schema compliance and returns "OK" for valid manifests or detailed error messages for issues, matching the validation logic used in the GitHub Actions pipeline.

### Can I test a plugin without installing it from the marketplace?

Yes. Use the `claude --plugin-dir ./folder` flag when starting Claude Code. This loads the plugin directly from your filesystem, bypassing the marketplace entirely and allowing you to test local changes immediately without publishing.

### Where are the CI validation scripts located in the repository?

The validation scripts reside in `.github/actions/validate-plugins/scripts/`. Key files include [`20-validate-cli-marketplace.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/20-validate-cli-marketplace.sh) for marketplace validation, [`30-validate-cli-external.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/30-validate-cli-external.sh) for external plugins, and [`40-validate-cli-local.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/40-validate-cli-local.sh) for local repository plugins. These scripts source the `cli_validate` function from [`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh).

### How do I provide API keys when testing locally?

Define required keys in the `userConfig` section of your [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest. When loading the plugin locally, Claude Code prompts you to enter these values, or you can create a `.env` file in the plugin root directory containing the key-value pairs for automated testing scenarios.