Advanced Usage Guide

Advanced installation methods, configuration options, and workflows for MAG Claude Plugins.

📚 Table of Contents

Global Plugin Installation
Local Development
Project-Specific Marketplace
Version Management
Plugin Updates
Custom Configuration

🌍 Global Plugin Installation

Overview

Global installation makes plugins available in all projects without per-project configuration.

When to Use

✅ Use global installation when:

Individual developer working alone
Testing a plugin before adding to team projects
Personal projects without team coordination
Quick experimentation

❌ Avoid global installation for:

Team projects (causes environment drift)
Production projects (not tracked in version control)
Projects requiring specific plugin versions

Installation Steps

# Step 1: Add marketplace globally (one-time)
/plugin marketplace add MadAppGang/claude-code

# Step 2: Install plugin globally
/plugin install frontend@mag-claude-plugins

# Step 3: Verify installation
/plugin list

Trade-offs

Advantages:

✅ Available in all projects immediately
✅ No per-project configuration needed
✅ Quick to test and experiment

Disadvantages:

❌ Not tracked in version control
❌ Team members must install manually
❌ Can cause environment drift across team
❌ Harder to manage plugin versions
❌ No project-specific plugin selection

Uninstalling Global Plugins

# Uninstall a plugin
/plugin uninstall frontend@mag-claude-plugins

# Verify removal
/plugin list

💻 Local Development

Overview

Test plugins from your local filesystem without publishing to a marketplace.

Use Cases

🔧 Developing new plugins
🐛 Debugging plugin issues
🧪 Testing plugin changes before committing
📦 Contributing to existing plugins

Setup

1. Add Local Marketplace

Point to your local clone of the repository:

/plugin marketplace add /Users/you/path/to/claude-code

2. Install Plugin from Local Source

/plugin install frontend@mag-claude-plugins

3. Make Changes to Plugin Files

Edit agents, commands, skills, or configurations in your local directory.

4. Reload Plugin

/plugin reload frontend@mag-claude-plugins

Note: Some changes may require a full Claude Code restart.

Development Workflow

# 1. Clone repository
git clone https://github.com/MadAppGang/claude-code.git
cd claude-code

# 2. Create feature branch
git checkout -b feature/my-new-agent

# 3. Make changes
# Edit plugins/frontend/agents/my-new-agent.md

# 4. Add to plugin.json
# Update plugins/frontend/plugin.json

# 5. Test locally
/plugin marketplace add /path/to/claude-code
/plugin install frontend@mag-claude-plugins

# 6. Verify changes work
# Test your new agent

# 7. Reload after changes
/plugin reload frontend@mag-claude-plugins

# 8. Commit and push
git add .
git commit -m "Add my-new-agent"
git push origin feature/my-new-agent

Debugging Tips

Plugin not loading:

# Check marketplace is added
/plugin marketplace list

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

# Verify plugin files exist
ls -la /path/to/claude-code/plugins/frontend

Changes not appearing:

# Reload plugin
/plugin reload frontend@mag-claude-plugins

# Or restart Claude Code completely

Agent/Command not found:

# Verify in plugin.json
cat /path/to/claude-code/plugins/frontend/plugin.json

# Check file exists
cat /path/to/claude-code/plugins/frontend/agents/your-agent.md

📁 Project-Specific Marketplace

Overview

Include marketplace configuration directly in project settings instead of adding it globally.

When to Use

🔐 Projects with restricted marketplace access
🏢 Enterprise environments with custom marketplaces
🎯 Projects requiring specific marketplace versions

Configuration

Add marketplace to .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "mag-claude-plugins": {
      "source": {
        "source": "github",
        "repo": "MadAppGang/claude-code"
      }
    }
  },
  "enabledPlugins": {
    "frontend@mag-claude-plugins": true,
    "code-analysis@mag-claude-plugins": true
  }
}

Trust Requirements

Important: This approach requires each developer to trust the project folder.

Why this is not recommended:

❌ Requires manual trust action per developer
❌ More complex than global marketplace approach
❌ Can cause confusion for team members
❌ Trust dialogs can be overlooked

Recommended approach instead:

✅ Add marketplace globally (one-time per developer)
✅ Enable plugins in project settings
✅ Simpler, clearer, fewer steps

🔢 Version Management

Specifying Versions in Marketplace

Control plugin versions in marketplace.json:

{
  "plugins": [
    {
      "name": "frontend",
      "version": "2.3.0",
      "source": "./plugins/frontend"
    }
  ]
}

Installing Specific Versions

# Install latest version
/plugin install frontend@mag-claude-plugins

# Install specific version
/plugin install frontend@mag-claude-plugins@2.2.0

# Verify installed version
/plugin list

Version Pinning

In project settings:

Currently, Claude Code enables the latest available version from the marketplace. Version pinning in project settings is not yet supported.

Workaround:

Pin versions in marketplace.json
Teams pull the same marketplace version from git

Checking Versions

# List installed plugins with versions
/plugin list

# Check marketplace version
cat .claude-plugin/marketplace.json | grep version

Upgrading Versions

# Update marketplace metadata
/plugin marketplace update mag-claude-plugins

# Reinstall plugin to get latest version
/plugin remove frontend@mag-claude-plugins
/plugin install frontend@mag-claude-plugins

🔄 Plugin Updates

Updating Marketplace

Get the latest marketplace metadata:

/plugin marketplace update mag-claude-plugins

This updates:

✅ Plugin versions
✅ New plugins added to marketplace
✅ Plugin descriptions and metadata
✅ Marketplace version

Does not update:

❌ Already installed plugin files (must reinstall)

Updating Individual Plugins

Method 1: Marketplace Update

# Update marketplace
/plugin marketplace update mag-claude-plugins

# Plugins will update automatically on next use

Method 2: Reinstall Plugin

# Remove and reinstall
/plugin remove frontend@mag-claude-plugins
/plugin install frontend@mag-claude-plugins

Method 3: Reload Plugin

For local development changes:

/plugin reload frontend@mag-claude-plugins

Update Workflow for Teams

For team projects:

# 1. One team member updates marketplace
/plugin marketplace update mag-claude-plugins

# 2. Check what changed
/plugin list

# 3. Test updated plugins

# 4. If all good, other team members run:
/plugin marketplace update mag-claude-plugins

No action needed by team members if:

Plugins are enabled in .claude/settings.json
Marketplace is already added globally
Updates are compatible

⚙️ Custom Configuration

Environment Variables

Plugins may require environment variables. Configure them in your shell profile or .env file:

In ~/.zshrc or ~/.bashrc:

# Frontend Plugin
export FIGMA_ACCESS_TOKEN="your-token"
export APIDOG_API_TOKEN="your-token"

# Optional
export CHROME_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
export CODEX_API_KEY="your-key"

In project .env file:

FIGMA_ACCESS_TOKEN=your-token
APIDOG_API_TOKEN=your-token

Check required variables:

See plugin's README.md
See plugin's DEPENDENCIES.md
Run /configure-mcp command (if available)

MCP Server Configuration

Some plugins include MCP servers that need configuration:

Auto-configuration (Recommended):

/configure-mcp

This command (available in frontend plugin):

Checks existing configuration
Asks for missing environment variables
Validates credentials
Updates MCP server configuration

Manual configuration:

Edit Claude Code's MCP configuration:

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-figma"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

Plugin-Specific Settings

Some plugins support additional configuration in .claude/settings.json:

{
  "enabledPlugins": {
    "frontend@mag-claude-plugins": true
  },
  "pluginConfig": {
    "frontend": {
      "defaultModel": "sonnet",
      "autoReview": true,
      "testingEnabled": true
    }
  }
}

Note: Plugin-specific config support varies by plugin. Check plugin documentation.

🎯 Best Practices

For Individual Developers

Add marketplace globally (one-time setup)
Enable plugins per-project (in .claude/settings.json)
Keep environment variables in shell profile
Update marketplace regularly for latest features

For Teams

Add marketplace globally (each developer, one-time)
Commit .claude/settings.json (team gets plugins automatically)
Document required env vars in project README
Use consistent plugin versions across team

For Plugin Developers

Test with local marketplace during development
Use semantic versioning for releases
Document breaking changes in CHANGELOG
Test updates before publishing

🐛 Troubleshooting

Marketplace Issues

Marketplace not found:

# List marketplaces
/plugin marketplace list

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

# Update marketplace
/plugin marketplace update mag-claude-plugins

Cannot access marketplace:

# Check internet connection
ping github.com

# Verify marketplace URL
/plugin marketplace list

# Try re-adding
/plugin marketplace remove mag-claude-plugins
/plugin marketplace add MadAppGang/claude-code

Plugin Issues

Plugin not appearing:

# Verify marketplace has plugin
/plugin marketplace list

# Check settings format
cat .claude/settings.json

# Reload Claude Code
# Restart the application

Plugin not working:

# Check plugin status
/plugin list

# Verify environment variables
echo $FIGMA_ACCESS_TOKEN

# Check plugin logs
# (if available in plugin documentation)

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

Version Issues

Wrong version installed:

# Check current version
/plugin list

# Update marketplace
/plugin marketplace update mag-claude-plugins

# Reinstall specific version
/plugin remove frontend@mag-claude-plugins
/plugin install frontend@mag-claude-plugins@2.3.0

📖 Related Documentation

Quick Start - Basic installation
Development Guide - Create plugins
Marketplace Reference - Technical reference
Troubleshooting - Common issues

📞 Need Help?

GitHub Issues: Report a problem
Email: i@madappgang.com
Documentation: Check plugin-specific README files

FilesExpand file tree

advanced-usage.md

Latest commit

History

advanced-usage.md

File metadata and controls

Advanced Usage Guide

📚 Table of Contents

🌍 Global Plugin Installation

Overview

When to Use

Installation Steps

Trade-offs

Uninstalling Global Plugins

💻 Local Development

Overview

Use Cases

Setup

1. Add Local Marketplace

2. Install Plugin from Local Source

3. Make Changes to Plugin Files

4. Reload Plugin

Development Workflow

Debugging Tips

📁 Project-Specific Marketplace

Overview

When to Use

Configuration

Trust Requirements

🔢 Version Management

Specifying Versions in Marketplace

Installing Specific Versions

Version Pinning

Checking Versions

Upgrading Versions

🔄 Plugin Updates

Updating Marketplace

Updating Individual Plugins

Update Workflow for Teams

⚙️ Custom Configuration

Environment Variables

MCP Server Configuration

Plugin-Specific Settings

🎯 Best Practices

For Individual Developers

For Teams

For Plugin Developers

🐛 Troubleshooting

Marketplace Issues

Plugin Issues

Version Issues

📖 Related Documentation

📞 Need Help?