Plugin Expert - Claude Code Plugin System Authority

Purpose: Authoritative source of truth for Claude Code's plugin system, marketplace management, and correct installation syntax.

When to Consult: ANY time you need to install, manage, or reference Claude Code plugins.

---

🚨 CRITICAL: Correct Plugin Installation Format

ALWAYS use this format:

/plugin install <plugin-name>

Examples:

# ✅ CORRECT
/plugin install specweave-github
/plugin install specweave-jira
/plugin install specweave-kubernetes

# ❌ WRONG - NEVER use @marketplace suffix
/plugin install specweave-github@specweave
/plugin install specweave-jira@specweave

Why this matters:

• Claude Code automatically resolves plugins from registered marketplaces
• The @marketplace syntax does NOT exist in Claude Code
• Using wrong syntax causes installation failures

---

Official Documentation

Primary Sources (ALWAYS defer to these):

1. Plugin System: https://code.claude.com/docs/en/plugins
2. Marketplaces: https://code.claude.com/docs/en/plugin-marketplaces
3. Blog Post: https://claude.com/blog/claude-code-plugins

---

Plugin Commands Reference

Installation

# Install plugin from registered marketplace
/plugin install <plugin-name>

# Examples
/plugin install specweave
/plugin install specweave-github
/plugin install specweave-jira

Marketplace Management

# List all available marketplaces
/plugin marketplace list

# Add marketplace (GitHub)
/plugin marketplace add <owner>/<repo>
# Example: /plugin marketplace add anton-abyzov/specweave

# Add marketplace (local directory - development only)
/plugin marketplace add /path/to/.claude-plugin

# Remove marketplace
/plugin marketplace remove <marketplace-name>

Plugin Management

# List installed plugins
/plugin list --installed

# List all available plugins from marketplaces
/plugin list

# Get plugin info
/plugin info <plugin-name>

# Uninstall plugin
/plugin uninstall <plugin-name>

# Update plugin
/plugin update <plugin-name>

---

SpecWeave Marketplace Setup

User Projects (Production)

SpecWeave automatically registers the GitHub marketplace during specweave init:

File: .claude/settings.json

{
  "extraKnownMarketplaces": {
    "specweave": {
      "source": {
        "source": "github",
        "repo": "anton-abyzov/specweave",
        "path": ".claude-plugin"
      }
    }
  }
}

Result: Claude Code fetches plugins from GitHub on-demand (no local copies)

SpecWeave Repo (Development)

For contributors working on SpecWeave itself:

# Add local marketplace (CLI only - settings.json doesn't support local paths)
/plugin marketplace add ./.claude-plugin

# Then install plugins
/plugin install specweave
/plugin install specweave-github

---

Available SpecWeave Plugins

Core (Auto-Installed)

• specweave - Framework essentials (increment planning, PM/Architect agents, living docs)
  • Auto-installed during specweave init
  • Provides: 9 skills, 22 agents, 22 commands, 8 hooks

Issue Trackers

• specweave-github - GitHub Issues integration

  • Install: /plugin install specweave-github
  • Provides: GitHub sync, PR automation, issue tracking

• specweave-jira - Jira integration

  • Install: /plugin install specweave-jira
  • Provides: Jira sync, epic management, sprint tracking

• specweave-ado - Azure DevOps integration

  • Install: /plugin install specweave-ado
  • Provides: ADO work items, boards, sprints

Tech Stacks

• specweave-frontend - React, Next.js, Vue, Angular

  • Install: /plugin install specweave-frontend
  • Provides: Frontend expert agent, component generation, design system integration

• specweave-kubernetes - K8s, Helm, kubectl

  • Install: /plugin install specweave-kubernetes
  • Provides: K8s expert agent, Helm chart generation, deployment validation

• specweave-ml - TensorFlow, PyTorch, ML workflows

  • Install: /plugin install specweave-ml
  • Provides: ML expert agent, training pipelines, model deployment

Utilities

• specweave-diagrams - Mermaid + C4 diagrams

  • Install: /plugin install specweave-diagrams
  • Provides: Architecture diagram generation, C4 model support

• specweave-docs-preview - Docusaurus documentation preview

  • Install: /plugin install specweave-docs-preview
  • Provides: Beautiful docs UI, hot reload, Mermaid rendering

---

Common Mistakes to Avoid

❌ Wrong: Using @marketplace Syntax

# NEVER DO THIS
/plugin install specweave-github@specweave
/plugin install specweave-jira@specweave

Why wrong: Claude Code doesn't support @marketplace suffix

Correct:

/plugin install specweave-github
/plugin install specweave-jira

❌ Wrong: Using Local Paths in settings.json

{
  "extraKnownMarketplaces": {
    "specweave": {
      "source": "./.claude-plugin"  // ❌ NOT supported
    }
  }
}

Why wrong: extraKnownMarketplaces in settings.json only supports remote sources (GitHub, Git)

Correct for development:

# Use CLI instead
/plugin marketplace add ./.claude-plugin

❌ Wrong: Forgetting Marketplace Registration

# Install without marketplace registered
/plugin install specweave-github  # ❌ Fails: marketplace not found

Correct:

# 1. Register marketplace first (or ensure settings.json has it)
/plugin marketplace add anton-abyzov/specweave

# 2. Then install plugins
/plugin install specweave-github

---

Troubleshooting

"Marketplace not found" Error

Symptom: /plugin install specweave-xxx fails with "marketplace not found"

Fix:

# Check registered marketplaces
/plugin marketplace list

# If specweave not listed, add it
/plugin marketplace add anton-abyzov/specweave

# Then retry install
/plugin install specweave-xxx

Plugin Not Auto-Activating

Symptom: Plugin installed but skills/agents not working

Causes:

1. Claude Code needs restart after plugin install
2. Skill description keywords don't match user's context
3. Plugin has errors (check plugin logs)

Fix:

# 1. Verify plugin installed
/plugin list --installed

# 2. Restart Claude Code

# 3. Check skill descriptions match your context

Installation Hangs or Fails

Symptom: /plugin install hangs or times out

Causes:

1. Network issues (GitHub fetch failed)
2. Marketplace not registered
3. Plugin doesn't exist in marketplace

Fix:

# 1. Check marketplace registered
/plugin marketplace list

# 2. Verify plugin exists
/plugin list  # Shows all available plugins

# 3. Check network connectivity
# Try re-adding marketplace (refreshes cache)
/plugin marketplace remove specweave
/plugin marketplace add anton-abyzov/specweave

---

How Other Skills Should Use This

Example: increment-planner skill recommending plugins

**Step 6: Detect Required Plugins**

When recommending plugins, ALWAYS use correct format:

✅ CORRECT:
📦 Install recommended plugins:
  /plugin install specweave-github
  /plugin install specweave-kubernetes

❌ WRONG:
  /plugin install specweave-github@specweave  # NEVER use @marketplace

Example: Auto-installation in TypeScript

// ✅ CORRECT
execFileNoThrowSync('claude', ['plugin', 'install', 'specweave-github']);

// ❌ WRONG
execFileNoThrowSync('claude', ['plugin', 'install', 'specweave-github@specweave']);

---

References

• Official Docs: https://code.claude.com/docs/en/plugins
• Marketplaces: https://code.claude.com/docs/en/plugin-marketplaces
• Blog: https://claude.com/blog/claude-code-plugins
• SpecWeave Marketplace: https://github.com/anton-abyzov/specweave/.claude-plugin

---

Last Updated: 2025-01-06 (v0.8.18)