How to Test Claude Plugins Locally: A Complete Development Guide

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, the manifest defines the plugin's skills, user-configurable parameters, and MCP server connections.

Manifest and Configuration Files

The plugin.json file contains the essential metadata, skill definitions, and userConfig schema for sensitive values like API keys. An optional 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.

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, 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.

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.

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 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:

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:

# 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. 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 for marketplace validation, 30-validate-cli-external.sh for external plugins, and 40-validate-cli-local.sh for local repository plugins. These scripts source the cli_validate function from .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 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.

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