Testing and debugging MAG Claude Plugins locally

This guide covers how to develop, test, and debug plugins locally before publishing to GitHub.

Use local development when:

• Creating new plugins
• Modifying existing plugins
• Testing changes before publishing
• Debugging plugin issues
• Contributing to the repository

Use GitHub installation when:

• Using plugins in production
• Installing on team projects
• Setting up plugins for the first time

• Claude Code installed and configured
• Git installed
• Node.js v18+ (for testing MCP servers)
• Text editor or IDE

# Clone from GitHub
git clone https://github.com/MadAppGang/claude-code.git

# Navigate to the directory
cd claude-code

claude-code/
├── .claude-plugin/
│   ├── marketplace.json          # Marketplace configuration
│   └── plugins/
│       └── frontend/  # Plugin directory
│           ├── plugin.json       # Plugin manifest
│           ├── agents/           # Agent markdown files
│           ├── commands/         # Command markdown files
│           ├── skills/           # Skill directories
│           └── mcp-servers/      # MCP configurations
├── docs/                         # User documentation
├── ai-docs/                      # Technical documentation
└── README.md                     # Main documentation

Add the local marketplace globally to test across all projects:

# Add local marketplace (use absolute path to your local clone)
/plugin marketplace add /path/to/claude-code

# Install plugin from local marketplace
/plugin install frontend@mag-claude-plugins

Result: Plugin available in all Claude Code projects from your local copy.

Use when:

• Testing plugin changes across multiple projects
• Developing new features
• Quick iteration cycles

Add local marketplace to a specific test project:

Step 1: Create test project .claude/settings.json

{
  "extraKnownMarketplaces": {
    "mag-claude-plugins": {
      "source": {
        "source": "local",
        "path": "/path/to/claude-code"
      }
    }
  },
  "enabledPlugins": {
    "frontend@mag-claude-plugins": true
  }
}

Step 2: Trust the folder

When Claude Code prompts to trust the folder, accept.

Result: Plugin only available in this test project.

Use when:

• Testing plugin in isolated environment
• Comparing local changes to published version
• Preventing accidental use of development version

Edit any plugin files:

# Example: Edit an agent
vim plugins/frontend/agents/typescript-frontend-dev.md

# Example: Edit a command
vim plugins/frontend/commands/implement.md

# Example: Update plugin manifest
vim plugins/frontend/plugin.json

After making changes, reload the plugin:

Method 1: Reinstall plugin

/plugin remove frontend@mag-claude-plugins
/plugin install frontend@mag-claude-plugins

Method 2: Restart Claude Code session

• Exit and restart Claude Code CLI
• Changes will be picked up automatically

Test your changes in a real project:

# Test a command
/implement Create a test component

# Test an agent directly
# Ask Claude to invoke the agent
"Use the typescript-frontend-dev agent to create a button component"

# Test a skill
# Skills are invoked automatically when relevant

Check that plugin is loaded correctly:

# List installed plugins
/plugin list

# Should show:
# frontend@mag-claude-plugins (global) - from /path/to/claude-code

1. Create a test agent:

# Create new agent file
touch plugins/frontend/agents/test-agent.md

2. Add agent frontmatter:

---
description: Test agent for debugging purposes
tools:
  - Read
  - Write
  - Bash
model: haiku
---

# Test Agent

This agent is for testing purposes only.

## Task

When invoked, this agent should:
1. Read the current directory
2. List files
3. Report back to the user

## Output Format

Provide a concise summary of findings.

3. Register agent in plugin.json:

{
  "agents": [
    "./agents/test-agent.md",
    "./agents/typescript-frontend-dev.md"
    // ... other agents
  ]
}

4. Reload and test:

/plugin remove frontend@mag-claude-plugins
/plugin install frontend@mag-claude-plugins

# Ask Claude to invoke test-agent

1. Create a test command:

touch plugins/frontend/commands/test-command.md

2. Add command content:

---
description: Test command for debugging
allowedTools:
  - Read
  - Bash
---

# Test Command

This command is for testing command execution.

## Task

Execute the following steps:

1. List files in current directory using Bash
2. Read package.json if it exists
3. Report findings to user

## Output

Provide a summary of the current project structure.

3. Register command in plugin.json:

{
  "commands": [
    "./commands/test-command.md",
    "./commands/implement.md"
    // ... other commands
  ]
}

4. Reload and test:

/plugin remove frontend@mag-claude-plugins
/plugin install frontend@mag-claude-plugins

# Test the command
/test-command

1. Configure test MCP server:

{
  "test-server": {
    "command": "node",
    "args": ["${CLAUDE_PLUGIN_ROOT}/test/mock-mcp-server.js"],
    "env": {
      "TEST_VAR": "test-value"
    }
  }
}

2. Create mock server (optional):

mkdir -p plugins/frontend/test

// test/mock-mcp-server.js
console.log('Mock MCP Server started');
console.log('TEST_VAR:', process.env.TEST_VAR);
console.log('CLAUDE_PLUGIN_ROOT:', process.env.CLAUDE_PLUGIN_ROOT);

3. Register in plugin.json:

{
  "mcpServers": {
    "test-server": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/test/mock-mcp-server.js"]
    }
  }
}

4. Test MCP server:

# Reload plugin
/plugin remove frontend@mag-claude-plugins
/plugin install frontend@mag-claude-plugins

# Check if MCP server is loaded
# Claude will have access to test-server tools

# Verify plugin is installed
/plugin list

# Should show local path:
# frontend@mag-claude-plugins (global)
#   from /path/to/claude-code

# Validate marketplace.json
cat .claude-plugin/marketplace.json | python -m json.tool

# Validate plugin.json
cat plugins/frontend/plugin.json | python -m json.tool

Ensure all paths in plugin.json are relative and correct:

{
  "agents": [
    "./agents/agent-name.md"     // ✅ Correct (relative path)
  ],
  "commands": [
    "./commands/command-name.md" // ✅ Correct (relative path)
  ],
  "skills": [
    "./skills/skill-name"        // ✅ Correct (relative path, directory)
  ]
}

Common mistakes:

{
  "agents": [
    "agents/agent-name.md",                                    // ❌ Missing ./
    "/full/path/agents/agent-name.md",                        // ❌ Absolute path
    "../plugins/frontend/agents/agent-name.md"    // ❌ Parent relative
  ]
}

# Check if agents are available
# Ask Claude: "What agents are available from the frontend plugin?"

# Test agent invocation
# Ask Claude: "Use the typescript-frontend-dev agent to create a test file"

# Verify CLAUDE_PLUGIN_ROOT expansion
# In your MCP server code, log the variable:
console.log('CLAUDE_PLUGIN_ROOT:', process.env.CLAUDE_PLUGIN_ROOT);

# Should output: /path/to/claude-code/plugins/frontend

Create a test project and use your local plugin:

# Create test project
mkdir -p ~/test-claude-plugin
cd ~/test-claude-plugin
npm init -y

# Create .claude/settings.json pointing to local marketplace
mkdir -p .claude
cat > .claude/settings.json << 'EOF'
{
  "extraKnownMarketplaces": {
    "mag-claude-plugins": {
      "source": {
        "source": "local",
        "path": "/path/to/claude-code"
      }
    }
  },
  "enabledPlugins": {
    "frontend@mag-claude-plugins": true
  }
}
EOF

# Start Claude Code and test
claude

Create a testing checklist:

• All agents invoke correctly
• All commands execute without errors
• Skills trigger when appropriate
• MCP servers connect successfully
• Environment variables expand correctly
• File paths resolve correctly
• Documentation is accurate

Keep two terminals open:

Terminal 1: Test project with local plugin

cd ~/test-claude-plugin
claude

Terminal 2: Test project with GitHub plugin

cd ~/test-claude-plugin-prod
claude

Compare behavior to ensure changes work as expected.

Symptoms:

• Plugin doesn't appear in /plugin list
• Commands not available
• Agents not invoking

Solutions:

1. Check marketplace path:

   # Ensure absolute path is correct
   /plugin marketplace list

2. Validate JSON syntax:

   cat .claude-plugin/marketplace.json | python -m json.tool
   cat plugins/frontend/plugin.json | python -m json.tool

3. Check file permissions:

   ls -la .claude-plugin/marketplace.json
   ls -la plugins/frontend/plugin.json

4. Reinstall plugin:

   /plugin remove frontend@mag-claude-plugins
   /plugin marketplace remove mag-claude-plugins
   /plugin marketplace add /path/to/claude-code
   /plugin install frontend@mag-claude-plugins

Symptoms:

• Made changes to agent/command but behavior unchanged
• Old version still running

Solutions:

1. Reinstall plugin:

   /plugin remove frontend@mag-claude-plugins
   /plugin install frontend@mag-claude-plugins

2. Restart Claude Code:

   • Exit Claude Code completely
   • Restart CLI
   • Check plugin version

3. Clear Claude cache (if available):

   # Check Claude Code docs for cache clearing command

Symptoms:

• MCP tools not available
• Connection errors

Solutions:

1. Check MCP configuration:

   cat plugins/frontend/plugin.json | grep -A 10 "mcpServers"

2. Verify command exists:

   # If using npx
   which npx
   
   # If using custom command
   ls -la ${CLAUDE_PLUGIN_ROOT}/bin/custom-mcp

3. Test command manually:

   # Navigate to plugin directory
   cd plugins/frontend
   
   # Test command
   npx -y @modelcontextprotocol/server-postgres

4. Check environment variables:

   # Ensure required env vars are set
   echo $APIDOG_API_TOKEN
   echo $FIGMA_ACCESS_TOKEN

Once you've tested changes locally, publish to GitHub:

cd /path/to/claude-code

# Stage changes
git add .

# Commit with descriptive message
git commit -m "Add new feature to typescript-frontend-dev agent"

# Push to main branch
git push origin main

# Or push to feature branch
git checkout -b feature/new-feature
git push origin feature/new-feature

After pushing, test the GitHub version:

# Remove local version
/plugin remove frontend@mag-claude-plugins
/plugin marketplace remove mag-claude-plugins

# Add GitHub version
/plugin marketplace add MadAppGang/claude-code

# Install from GitHub
/plugin install frontend@mag-claude-plugins

# Test to ensure changes work

If making significant changes, update version numbers:

In .claude-plugin/marketplace.json:

{
  "plugins": [
    {
      "name": "frontend",
      "version": "1.1.0",  // ← Update version
      "source": "./plugins/frontend"
    }
  ]
}

In plugins/frontend/plugin.json:

{
  "name": "frontend",
  "version": "1.1.0",  // ← Update version
  "description": "..."
}

# Create feature branch
git checkout -b feature/new-agent

# Make changes
# Test thoroughly

# Push feature branch
git push origin feature/new-agent

# Create PR on GitHub

Always test new features in isolated test projects before using in production projects.

Update relevant documentation:

• README.md - If adding new features
• docs/frontend.md - If changing workflows
• DEPENDENCIES.md - If adding new dependencies
• ai-docs/ - If changing architecture

Pre-publish checklist:

• All JSON files valid
• File paths correct (relative, not absolute)
• Environment variables documented
• README updated
• Version numbers updated
• Tested in fresh project
• No secrets in git

# Regularly pull latest changes
git pull origin main

# Push your changes
git push origin main

# Update version after publishing
git tag v1.1.0
git push --tags

# Marketplace management
/plugin marketplace add /path/to/claude-code
/plugin marketplace remove mag-claude-plugins
/plugin marketplace list

# Plugin management
/plugin install frontend@mag-claude-plugins
/plugin remove frontend@mag-claude-plugins
/plugin list

# Validation
cat .claude-plugin/marketplace.json | python -m json.tool
cat plugins/frontend/plugin.json | python -m json.tool

# Git
git status
git add .
git commit -m "message"
git push origin main

# Marketplace root (replace with your local path)
/path/to/claude-code

# Marketplace config
/path/to/claude-code/.claude-plugin/marketplace.json

# Plugin root
/path/to/claude-code/plugins/frontend

# Plugin manifest
/path/to/claude-code/plugins/frontend/plugin.json

Issues with local development:

1. Check this guide first
2. Verify JSON syntax
3. Check file permissions
4. Review Claude Code docs: https://docs.claude.com/en/docs/claude-code/plugins
5. Open issue: https://github.com/MadAppGang/claude-code/issues

Contact:

• Email: i@madappgang.com
• GitHub: https://github.com/MadAppGang/claude-code

Last Updated: November 2024 Maintained by: Jack Rudenko @ MadAppGang