Quick Reference

CLAUDE.md

Development guidance for Claude Code when working with this plugin marketplace.

Quick Reference

# Validation
claude plugin validate .

# Local testing
/plugin marketplace add .
/plugin install <plugin>@wookstar-claude-plugins
/plugin marketplace update wookstar

# After changes
/plugin marketplace update wookstar

Official Documentation: https://docs.claude.com/en/docs/claude-code/plugin-marketplaces.md

Architecture Decisions

Consolidated Structure (v6.0)

All plugins live inside the plugins/ directory for consistent organisation:

• Standalone plugins - focused plugins with skills, agents, commands, and optionally MCP servers
• MCP-only plugins - individual MCP server integrations (prefixed with mcp-)

Why this approach:

• All plugins in one location for easy discovery
• Each plugin has its own .claude-plugin/plugin.json manifest
• MCP servers declared in marketplace.json with file references
• Cross-platform compatible paths (forward slashes)

Directory Structure

wookstar-claude-plugins/
├── .claude-plugin/
│   └── marketplace.json         # Root manifest (defines all plugins)
├── plugins/                     # ALL plugins live here
│   ├── claudecode/              # Commands-only plugin
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json
│   │   ├── README.md
│   │   └── commands/*.md
│   ├── developer/               # Plugin with MCP servers
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json
│   │   ├── .mcp.json            # MCP server configurations
│   │   ├── agents/*.md
│   │   ├── commands/*.md
│   │   └── skills/<name>/SKILL.md
│   ├── documents/
│   ├── message/                 # Rich text message drafts for Gmail, Outlook, and WhatsApp
│   ├── shopify-developer/
│   ├── ultimate-skill-creator/
│   ├── timezone-tools/          # Renamed from utilities
│   ├── google-apps-script/      # Extracted from productivity
│   ├── tampermonkey/            # Extracted from productivity
│   ├── git-worktrees/           # New (from productivity commands)
│   ├── google-tagmanager/       # Extracted from marketing
│   ├── google-analytics/        # Extracted from marketing
│   ├── google-ads-scripts/      # Extracted from marketing
│   ├── codex/                   # OpenAI Codex CLI headless mode
│   ├── gemini/                  # Gemini CLI headless mode
│   ├── ffmpeg/                  # FFmpeg CLI reference
│   ├── mcp-alphavantage/        # MCP-only plugins
│   ├── mcp-cloudflare/
│   ├── mcp-coingecko/
│   ├── mcp-currency-conversion/
│   ├── mcp-excalidraw/
│   ├── mcp-fetch/
│   ├── mcp-gemini-bridge/
│   ├── mcp-google-workspace/
│   ├── mcp-mikrotik/
│   ├── mcp-n8n/
│   ├── mcp-notion/
│   ├── mcp-open-meteo/
│   └── mcp-perplexity/
└── docs/                        # Development reference files

Auto-Loading Rules

Claude Code auto-discovers components within each plugin:

MCP Configuration Rules

CRITICAL: MCP servers use file references in marketplace.json, NOT in plugin.json.

// In marketplace.json entry:
"mcpServers": "./.mcp.json"

// plugin.json does NOT need mcpServers field

Why this pattern:

1. Single source of truth - MCP config in one place
2. Marketplace controls which MCPs are loaded
3. plugin.json stays minimal (name, description, version, author)

Validation checklist:

• .mcp.json exists in plugin directory (for MCP plugins)
• marketplace.json uses "mcpServers": "./.mcp.json"
• plugin.json does NOT duplicate mcpServers
• claude plugin validate . passes

Adding Components

New Full-Featured Plugin

1. Create directory: plugins/<plugin-name>/
2. Create .claude-plugin/plugin.json with name, description, version, author
3. Create README.md for documentation
4. Add component directories: agents/, commands/, skills/
5. Add entry to .claude-plugin/marketplace.json
6. Test: /plugin install <plugin>@wookstar-claude-plugins

New MCP-Only Plugin

1. Create directory: plugins/mcp-<name>/
2. Create .claude-plugin/plugin.json (without mcpServers)
3. Create .mcp.json with server configuration
4. Create README.md for documentation
5. Add entry to marketplace.json with "mcpServers": "./.mcp.json"
6. Test: /plugin install mcp-<name>@wookstar-claude-plugins

Command/Agent (to existing plugin)

1. Create file: plugins/<plugin>/commands/<name>.md or plugins/<plugin>/agents/<name>.md
2. Auto-loaded on marketplace update
3. Test: /plugin marketplace update wookstar

Skill (to existing plugin)

1. Create: plugins/<plugin>/skills/<skill-name>/SKILL.md
2. Optional subdirectories: assets/, references/, scripts/
3. Auto-loaded on marketplace update

MCP Server (embedded in plugin)

1. Create/edit: plugins/<plugin>/.mcp.json
2. Add "mcpServers": "./.mcp.json" to marketplace.json entry
3. Test: /plugin install <plugin>@wookstar-claude-plugins

Critical Files

.claude-plugin/marketplace.json

Root manifest containing:

• Marketplace metadata (name, version)
• All plugin definitions with source paths
• Plugin metadata (version, description, keywords, category)
• MCP server file references

Path resolution:

• "source": "./plugins/developer" - plugin root
• "mcpServers": "./.mcp.json" - relative to plugin source

plugins//.claude-plugin/plugin.json

Plugin manifest (required for each plugin):

{
  "name": "plugin-name",
  "description": "Plugin description",
  "author": {
    "name": "Henrik Soederlund",
    "email": "whom-wealthy.2z@icloud.com"
  },
  "version": "1.0.0"
}

plugins//.mcp.json

MCP server configurations (for plugins with MCP servers):

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["package-name"],
      "env": { "API_KEY": "${ENV_VAR}" }
    }
  }
}

Version Management

Marketplace version: Updated for architectural changes (currently 6.0.0) Plugin versions: Independent semantic versioning per plugin

Follow semantic versioning:

• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes

Constraints

1. No build process - pure marketplace, no compilation
2. All plugins in plugins/ - consistent organisation
3. MCP file references - never inline configurations in marketplace.json
4. MCP in marketplace only - plugin.json does not include mcpServers
5. Markdown format - commands and agents are .md files
6. Forward slashes - cross-platform path compatibility
7. Environment variable security - never commit secrets

Testing Checklist

Before committing:

1. Run claude plugin validate .
2. Install plugin locally and verify components load
3. Test commands, agents, and skills function correctly
4. Update plugin version if needed (MAJOR/MINOR/PATCH)
5. Commit with semantic message