Tool Advisor Plugin

Intelligently analyze installed plugins, skills, and agents to recommend the best tools for any given project or task.

Overview

Tool Advisor helps you leverage your full Claude Code toolkit by:

• 🔍 Scanning and indexing all installed plugins, skills, and agents
• 🎯 Recommending the best tools for your tasks
• 💡 Proactively suggesting relevant tools during conversations
• 📚 Helping you discover capabilities you didn't know you had

Features

Commands

• /tool-advisor:recommend [task] - Get tool recommendations for a specific task

  /tool-advisor:recommend "deploy to production"
  /tool-advisor:recommend --task "code review" --prefer agent

• /tool-advisor:scan-tools - Scan and index all available tools

  /tool-advisor:scan-tools

• /tool-advisor:show-capabilities - List all available tools

  /tool-advisor:show-capabilities
  /tool-advisor:show-capabilities --all

Agents

• tool-scanner - Automatically scans .claude/ directories for capabilities
• recommendation-engine - Matches tasks to the best available tools
• proactive-advisor - Suggests relevant tools during conversations

Skills

• auto-optimize - Automatically reads Project.md, asks clarifying questions, and spawns coordinated agents for project execution

  • Triggers: "read my Project.md and get started", "optimize my setup", "auto-optimize"
  • Use case: Project kickoff and initial setup with automated workflow orchestration

• workflow-orchestrator - Analyzes current conversation context and spawns agents mid-workflow

  • Triggers: "summarize and launch agents", "spawn agents for this work", "orchestrate the workflow"
  • Use case: Mid-project task delegation and agent coordination
  • Manual invoke: Skill(skill="tool-advisor:workflow-orchestrator")

• discovery - Techniques for discovering and analyzing installed tools

• recommendation - Algorithms for matching tasks to tools

Hooks

• pre-tool-call - Checks for better specialized tools before execution
• post-tool-call - Suggests alternatives after tool execution
• conversation-start - Auto-scans tools when Claude starts
• user-prompt-submit - Proactively suggests tools based on user requests

Installation

Prerequisites

• Claude Code v1.0.0 or later
• Bash (for utility scripts)

Install Plugin

# Plugin is already installed at:
~/.claude/plugins/tool-advisor/

# Verify installation
ls ~/.claude/plugins/tool-advisor/

Configuration

Create .claude/tool-advisor.local.md in your project or home directory to customize behavior:

# Enable/disable proactive suggestions
proactive_suggestions: true

# Auto-use tool if confidence exceeds this threshold
auto_use_threshold: 0.90

# Show suggestion if confidence exceeds this threshold
suggestion_threshold: 0.70

# Scan tools on conversation start
scan_on_start: true

# Scan frequency: hourly, daily, manual
scan_frequency: hourly

# Directories to scan (defaults shown)
scan_directories:
  - ~/.claude/plugins/
  - ~/.claude/skills/
  - ./.claude/

# Verbosity: quiet, normal, verbose
verbosity: normal

# Show match percentages in recommendations
show_scores: true

# Exclude plugins matching these patterns
exclude_plugins:
  - "legacy-*"
  - "deprecated-*"

# Preferred tools for specific task types
preferred_tools:
  deploy: "cloud-infrastructure"
  review: "code-review-ai"
  test: "tdd-workflows"

Usage Examples

Get Recommendations

# Simple recommendation
/tool-advisor:recommend "review this pull request"

# Structured recommendation
/tool-advisor:recommend --task "deploy to AWS" --prefer agent --exclude "legacy-*"

Scan Your Tools

# Full scan with progress
/tool-advisor:scan-tools

# Quiet scan (updates cache silently)
/tool-advisor:scan-tools --quiet

Browse Capabilities

# Grouped view
/tool-advisor:show-capabilities

# Full view with examples
/tool-advisor:show-capabilities --all

How It Works

1. Discovery Phase

The tool-scanner agent scans:

• ~/.claude/plugins/ - User plugins
• ~/.claude/skills/ - User skills
• Project .claude/ directory
• Connected MCP servers
• Built-in Claude Code tools

2. Indexing

Creates searchable index at .claude/tool-advisor-cache.json containing:

• Tool names and types
• Capabilities and descriptions
• Keyword mappings
• Usage metadata

3. Recommendation Engine

When you describe a task, the recommendation engine:

1. Analyzes your request (keywords, intent, context)
2. Searches the capability index
3. Scores matches using multi-factor algorithm:
   • Keyword match: 35%
   • Capability type: 25%
   • User history: 20%
   • Tool freshness: 10%
   • Success rate: 10%
4. Returns ranked recommendations

4. Proactive Suggestions

During conversations, the proactive-advisor agent:

• Monitors for task keywords (deploy, test, review, etc.)
• Detects question patterns ("how do I", "can you help")
• Checks error contexts for relevant tools
• Suggests tools inline: "💡 Using: [tool-name] (94% match)"

Files and Structure

tool-advisor/
├── .claude-plugin/
│   └── plugin.json          # Plugin manifest
├── README.md                # This file
├── skills/
│   ├── auto-optimize/
│   │   └── SKILL.md        # Project kickoff automation
│   ├── workflow-orchestrator/
│   │   └── SKILL.md        # Mid-workflow agent spawning
│   ├── discovery/
│   │   ├── SKILL.md        # Plugin discovery techniques
│   │   └── references/     # Detailed reference docs
│   └── recommendation/
│       └── SKILL.md        # Recommendation algorithms
├── agents/
│   ├── tool-scanner.md     # Scans .claude/ directories
│   ├── recommendation-engine.md
│   └── proactive-advisor.md
├── commands/
│   ├── recommend.md        # /tool-advisor:recommend
│   ├── scan-tools.md       # /tool-advisor:scan-tools
│   └── show-capabilities.md
├── hooks/
│   └── hooks.json          # Hook configurations
└── scripts/
    ├── scan-plugins.sh     # Discovers plugins
    ├── build-index.sh      # Creates search index
    └── parse-manifest.sh   # Extracts capabilities

Troubleshooting

Cache Issues

If recommendations seem stale:

/tool-advisor:scan-tools

No Recommendations

Check that cache exists:

ls ~/.claude/tool-advisor-cache.json

Disable Proactive Mode

Edit .claude/tool-advisor.local.md:

proactive_suggestions: false

Contributing

Contributions welcome! This plugin follows the Claude Code plugin development best practices.

License

MIT License - See LICENSE file for details