name: plugin-discovery
version: 1.0.0
description: This skill should be used when searching for, installing, or managing Claude plugins that provide specialized agents, commands, and MCP servers. Before starting work on tasks involving specific technologies, frameworks, or domains, proactively check if a plugin exists that encodes best practices and specialized knowledge. Plugins provide tools and techniques that enhance base capabilities. Also use when users explicitly ask to find, install, or manage plugins.
license: MIT
keywords: [plugins, marketplace, discovery, install, cli, management]

Plugin Discovery

Discover, install, and manage Claude plugins providing specialized agents, commands, and MCP servers.

Table of Contents

• Requirements
• Quick Start
• Security Considerations
• Basic Commands
• Clarifying Ambiguous Requests
• Discovery
• Plugin Management
• Marketplace Management
• Maintenance
• Presenting Results
• Bundled Resources
• Test Scenarios

Requirements

This skill requires the following tools:

• claude CLI - Installed with Claude Code (required)
• jq - For JSON parsing in examples - Install: brew install jq or apt-get install jq
• curl - For API queries (usually pre-installed)
• tree - For directory visualization (optional) - Install: brew install tree

Quick Start

# Search for plugins
claude plugin list --available

# Install a plugin (user scope - global)
claude plugin install plugin-name

# Install for current project only
claude plugin install plugin-name --scope project

# List installed plugins
claude plugin list

# Run diagnostics
./scripts/doctor.sh  # From this skill's directory

Security Considerations

This skill executes shell commands via the claude CLI and external APIs. Be aware:

• Command Execution: Claude will run bash commands shown in examples. Review complex scripts before execution.
• Destructive Operations: Commands like rm -rf in the doctor workflow permanently delete files.
• External API Calls: Queries to claude-plugins.dev fetch plugin metadata from a public registry.
• Plugin Installation: Installing plugins gives them access to your Claude Code environment. Only install plugins from trusted sources.
• Script Permissions: Some workflows create and execute shell scripts. Verify script content before running.

When in doubt, review the command before confirming execution.

Basic Commands

Command Reference

claude plugin
├── install <plugin> [--scope user|project|local]
├── uninstall <plugin> [--scope user|project|local]
├── update <plugin> [--scope user|project|local|managed]
├── list [--json] [--available]
├── validate <path>
└── marketplace
    ├── add <source>
    ├── remove <name>
    ├── update [name]
    └── list [--json]

Scopes:
- user — Global, available across all projects (default)
- project — Local to specific project, shared with team
- local — Local installation, gitignored

Note: As of Claude CLI v1.x, enable/disable commands may not work reliably. Prefer uninstall/reinstall for toggling plugins.

Help System

When user types /plugin-discovery help, show:

plugin-discovery - Discover, install, and manage Claude plugins

Example usage:
  /plugin-discovery search TEXT         Search plugins by name/description
  /plugin-discovery info PLUGIN...      Show detailed plugin information
  /plugin-discovery install PLUGIN...   Install plugins
  /plugin-discovery uninstall PLUGIN... Remove plugins
  /plugin-discovery update [PLUGIN...]  Update plugins (or all)
  /plugin-discovery list                List installed plugins
  /plugin-discovery list --available    List all available plugins
  /plugin-discovery doctor              Run diagnostics and cleanup
  /plugin-discovery which COMPONENT     Find which plugin owns a component

Clarifying Ambiguous Requests

IMPORTANT: Before proceeding with any plugin operation, clarify ambiguous requests with the user.

"List plugins" scenarios

When user asks to "list plugins" without specifying what kind, ask:

questions:
  - id: list_type
    prompt: "What plugins would you like to list?"
    options:
      - id: installed
        label: "Installed plugins only"
      - id: available
        label: "Available plugins (installed + can install from added marketplaces)"
      - id: search_online
        label: "Search online registry (claude-plugins.dev)"

• Installed: Show only currently installed plugins
• Available: Show installed + available from added marketplaces
• Search online: Query claude-plugins.dev registry

Search Strategy

Before searching, ask user:

questions:
  - id: search_source
    prompt: "Where should I search for plugins?"
    options:
      - id: local
        label: "Local only (installed + available from added marketplaces)"
      - id: registry
        label: "Registry only (claude-plugins.dev)"
      - id: both
        label: "Both local and registry"

• Local: Fast, searches installed + available from added marketplaces
• Registry: Full claude-plugins.dev catalog (requires adding marketplace before install)
• Both: Comprehensive search across all sources

Discovery

List installed plugins

claude plugin list

Shows plugins with name, version, scope, and status (enabled/disabled).

List all available plugins

claude plugin list --available

Shows both installed and available plugins from added marketplaces.

Search local plugins

# Plain text search
claude plugin list --available | grep "search-term"

# JSON parsing (if your CLI version supports it)
claude plugin list --available --json | jq '.[] | select(.name | contains("search-term"))'

Filter by searching name and description fields for query terms.

Search registry (claude-plugins.dev)

curl "https://claude-plugins.dev/api/plugins?q=QUERY&limit=20&offset=0"

Response fields:
- name, description, namespace, gitUrl
- stars, downloads, verified
- metadata.agents, metadata.commands, metadata.mcpServers

Web registry: https://claude-plugins.dev/plugins

Plugin Management

Install plugin

From local marketplace (already added):

claude plugin install plugin-name              # user scope (default)
claude plugin install plugin-name --scope project
claude plugin install plugin-name --scope local

From registry (must add marketplace first):

# 1. Add marketplace
claude plugin marketplace add owner/repo

# 2. Install plugin
claude plugin install plugin-name --scope project

Uninstall plugin

# Find scope first
claude plugin list --json | jq -r '.[] | select(.id | contains("plugin-name")) | .scope'

# Uninstall from found scope
claude plugin remove plugin-name --scope <scope>

Update plugin

claude plugin update plugin-name --scope user

Restart Claude Code to apply updates.

Marketplace Management

List marketplaces

claude plugin marketplace list

Shows marketplace name, source, and repository.

Add marketplace

# GitHub repo
claude plugin marketplace add owner/repo

# URL
claude plugin marketplace add https://github.com/owner/repo.git

# Local path
claude plugin marketplace add /path/to/marketplace

Remove marketplace

claude plugin marketplace remove marketplace-name

Update marketplace(s)

# Update all marketplaces
claude plugin marketplace update

# Update specific marketplace
claude plugin marketplace update marketplace-name

Maintenance

Validate plugin

# Validate installed plugin
INSTALL_PATH=$(claude plugin list --json | jq -r '.[] | select(.id | contains("plugin-name")) | .installPath')
claude plugin validate $INSTALL_PATH

Returns: ✔ Validation passed or error details.

Doctor (cleanup & diagnostics)

Run the bundled doctor script for comprehensive health checks:

# From this skill's directory
./scripts/doctor.sh

The doctor script:
1. Validates all installed plugins
2. Checks for orphan cache directories
3. Detects duplicates across scopes
4. Validates marketplace health

See scripts/doctor.sh for the full implementation.

Presenting Results

When showing plugins to users:

1. Clarify first — If request is ambiguous (see "Clarifying Ambiguous Requests" section)
2. Show 3-5 most relevant — Don't overwhelm with hundreds
3. Include key info — Name, status, description, stars/downloads
4. Prioritize — Installed > high downloads > high stars
5. Explain relevance — How it helps their specific task
6. Ask confirmation — Before installing/removing
7. Offer alternatives — Can help directly if no suitable plugin

Bundled Resources

This skill includes additional reference materials:

1. references/advanced-commands.md
2. Advanced plugin information workflows
3. Complex search patterns with jq
4. Scope management commands
5. Component discovery scripts

6. Marketplace filtering techniques

7. references/troubleshooting.md

8. Common issues and solutions
9. Error message explanations
10. Diagnostic procedures

11. Resolution step-by-step guides

12. scripts/doctor.sh

13. Comprehensive health check script
14. Validates all installed plugins
15. Detects orphan directories
16. Identifies duplicate installations
17. Validates marketplace integrity

When to use bundled resources:
- User needs advanced filtering or complex jq patterns → advanced-commands.md
- User encounters errors or plugin not working → troubleshooting.md
- User wants comprehensive diagnostics → Run scripts/doctor.sh

Test Scenarios

Use these scenarios to verify the skill works correctly across different use cases:

Scenario 1: Basic Plugin Discovery

User Request: "Find me a plugin for Neo4j graph databases"

Expected Behavior:
1. Ask clarifying question: "Where should I search for plugins?" (local/registry/both)
2. Execute appropriate search command based on user choice
3. Present 3-5 most relevant results with names, descriptions, and download counts
4. Explain relevance to Neo4j graph database work

Verification: Results should include neo4j-dev or similar plugins

Scenario 2: Plugin Installation with Scope Selection

User Request: "Install the superpowers plugin for my current project"

Expected Behavior:
1. Identify plugin name and marketplace (if ambiguous, ask for clarification)
2. Ask for installation scope or infer from "current project" → --scope project
3. Check if marketplace is already added (if not, add it first)
4. Execute: claude plugin install superpowers --scope project
5. Confirm successful installation

Verification: Plugin appears in claude plugin list with project scope

Scenario 3: Troubleshooting Plugin Issues

User Request: "My installed plugins aren't showing up. Can you help diagnose the issue?"

Expected Behavior:
1. Run diagnostic checks or suggest running doctor script
2. Validate plugin manifests
3. Check for common issues (wrong scope, needs restart, etc.)
4. Present findings with severity levels
5. Suggest specific fixes for identified issues

Verification: Doctor workflow identifies system state and suggests remediation

Scenario 4: Marketplace Management

User Request: "Add the superpowers marketplace and show me what plugins it has"

Expected Behavior:
1. Add marketplace: claude plugin marketplace add obra/superpowers-marketplace
2. Wait for marketplace to be added
3. List available plugins from that marketplace
4. Present results in table format with plugin names, versions, and descriptions

Verification: Marketplace appears in claude plugin marketplace list

Scenario 5: Complex Query - Finding Plugin Owner

User Request: "Which plugin provides the 'cypher' skill?"

Expected Behavior:
1. Use the component discovery workflow from advanced-commands.md
2. Search through installed plugin manifests
3. Report which plugin(s) contain the component
4. Show relevant details from the plugin manifest

Verification: Correctly identifies the plugin containing a "cypher" skill file

Version: 1.0.0
Last verified: 2026-01-27