gh-hyperskill-claude-code-marketplace-plugins-plugin-development/skills/plugin-authoring/examples/testing-workflow.md

Testing Workflow

A step-by-step guide to testing plugins locally during development.

Overview

Testing plugins locally uses a dev marketplace that points to your working plugin directory. This allows you to:

• Test changes without publishing
• Iterate quickly
• Validate before distribution

Setup: One-Time

1. Create Dev Marketplace Structure

# From your project root
mkdir -p dev-marketplace/.claude-plugin

2. Create marketplace.json

Create dev-marketplace/.claude-plugin/marketplace.json:

{
  "name": "dev-marketplace",
  "owner": {
    "name": "Developer"
  },
  "metadata": {
    "description": "Local development marketplace",
    "version": "0.1.0"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "description": "Plugin under development",
      "source": "../plugins/my-plugin"
    }
  ]
}

Key: source points to your plugin directory (relative path from marketplace).

3. Add Marketplace to Claude Code

claude
/plugin marketplace add ./dev-marketplace

Verify:

/plugin marketplace list

You should see dev-marketplace listed.

Iteration Loop

Install Plugin

/plugin install my-plugin@dev-marketplace

Test Commands

/my-plugin:command-name args

Or test via /help to see if commands appear.

Make Changes

Edit your plugin files (commands, skills, etc.).

Reinstall

/plugin uninstall my-plugin@dev-marketplace
/plugin install my-plugin@dev-marketplace

Note: You must uninstall/reinstall to pick up changes.

Repeat

Continue the edit → reinstall → test cycle.

Validation

Before each test cycle, validate your plugin:

/plugin-development:validate

This checks:

• plugin.json exists and is valid JSON
• Component directories exist
• Paths are correct
• No common mistakes

Debugging

Plugin Not Loading

1. Check plugin.json exists at .claude-plugin/plugin.json
2. Verify JSON syntax: cat .claude-plugin/plugin.json | jq .
3. Check paths are relative: ./commands/ not /absolute/path/

Commands Not Showing

1. Verify commands field in plugin.json points to ./commands/
2. Check command files have .md extension
3. Verify frontmatter has description field
4. Reinstall the plugin

Hooks Not Running

1. Check hooks field in plugin.json points to correct path
2. Verify hooks.json is valid JSON
3. Make scripts executable: chmod +x scripts/*.sh
4. Test script directly: ./scripts/validate-plugin.sh
5. Use claude --debug to see hook execution

Skills Not Triggering

1. Check skills field in plugin.json (if specified)
2. Verify SKILL.md has frontmatter with name and description
3. Ensure name matches directory name (lowercase, hyphenated)
4. Check description includes clear trigger conditions

Advanced: Debug Mode

Run Claude Code in debug mode to see detailed plugin loading:

claude --debug

This shows:

• Plugin registration
• Component discovery
• Hook execution
• Tool usage

Look for errors related to your plugin in the output.

Multiple Plugins

You can test multiple plugins from one dev marketplace:

{
  "plugins": [
    {
      "name": "plugin-one",
      "source": "../plugins/plugin-one"
    },
    {
      "name": "plugin-two",
      "source": "../plugins/plugin-two"
    }
  ]
}

Install each separately:

/plugin install plugin-one@dev-marketplace
/plugin install plugin-two@dev-marketplace

Clean Up

Uninstall Plugin

/plugin uninstall my-plugin@dev-marketplace

Remove Marketplace

/plugin marketplace remove dev-marketplace

Best Practices

1. Validate first: Always run /plugin-development:validate before testing
2. Small changes: Test incrementally, don't make many changes at once
3. Check logs: Use --debug when troubleshooting
4. Script testing: Test hook scripts directly before adding to hooks.json
5. Clean installs: Uninstall fully before reinstalling to avoid cache issues

Troubleshooting Checklist

□ plugin.json exists and is valid JSON
□ All paths are relative (start with ./)
□ Component directories exist (commands/, etc.)
□ Command files have .md extension
□ Scripts are executable (chmod +x)
□ marketplace.json plugin name matches plugin.json name
□ Reinstalled after making changes

Example Session

# One-time setup
mkdir -p dev-marketplace/.claude-plugin
# ... create marketplace.json ...
/plugin marketplace add ./dev-marketplace

# Development loop
/plugin install my-plugin@dev-marketplace
/my-plugin:test-command

# Make changes to plugin files...

/plugin-development:validate
/plugin uninstall my-plugin@dev-marketplace
/plugin install my-plugin@dev-marketplace
/my-plugin:test-command

# Repeat...