claude-multi-agent-research-system-skill

Claude Code Multi-Agent Research Skill

Orchestrated multi-agent research with architectural enforcement, parallel execution, and comprehensive audit trails.

🎉 v2.5.2: Fresh Clone Auto-Detection Fix

A tri-skill platform with smart routing, auto-indexing, and compound request detection:

Key Features:

• Auto-Reindex on File Changes - Triggers on Write/Edit with 5-min cooldown (IndexFlatIP auto-fallback (full reindex only))
• Auto-Reindex on Session Start - Smart change detection when Claude Code starts
• Comprehensive Decision Tracing - Full visibility into reindex decisions (skip reasons, timing, errors)
• Smart Compound Detection - When prompts trigger multiple skills, asks for clarification
• 200+ Trigger Keywords - Automatic skill routing via hook (3 skills)
• Quality Gates - 85% threshold with max 3 iterations
• Token Savings - Semantic search saves 5,000-10,000 tokens per task (~90% reduction)

Quick Examples:

research quantum computing fundamentals     → multi-agent-researcher
plan a task management PWA with offline     → spec-workflow-orchestrator
find authentication logic in the codebase   → semantic-search
research auth methods and build login page  → asks which skill to use

See Planning Workflow and CHANGELOG.md for details.

Table of Contents

• Quick Start
  • Prerequisites
  • Installation
  • Post-Installation: CLAUDE.md Setup
  • Fresh Clone Quick Start
  • Your First Research Query
• Why This Approach?
  • vs. Direct Tools (WebSearch/WebFetch)
  • vs. MCP Servers
  • vs. Sequential Research
  • Architectural Benefits
  • When NOT to Use
• How It Works
  • Phase 1: Decomposition
  • Phase 2: Parallel Research
  • Phase 3: Synthesis
  • Phase 4: Delivery
• Planning Workflow (New in v2.2.0)
• Semantic-Search Workflow (RAG System)
  • What is RAG?
  • Trigger Keywords
  • Agent Roles
  • RAG Workflow Details
  • Features
  • Benefits Over Traditional Search
• Testing
• Configuration
  • File Structure
  • File & Directory Reference
  • Environment Variables
  • Advanced Setup
• Architecture Deep Dive
  • Comparison to Reference SDK
  • Enforcement Mechanisms
  • Hooks Architecture
  • Session Logging
• Troubleshooting
• Inspiration & Credits
• Author & Acknowledgments
• License
• References

Quick Start

Prerequisites

Required for All Features:

• Claude Code installed (Pro, Max, Team, or Enterprise tier)[1]
• Python 3.8+ with python3 command available in PATH
  • Verify: python3 --version (should show 3.8 or higher)
• Git installed and available in PATH
• Bash shell (for hooks and scripts)
  • macOS/Linux: built-in
  • Windows: Use WSL2 (Windows Subsystem for Linux)

Additional for Semantic-Search Skill (optional):

The semantic-search skill implements RAG (Retrieval-Augmented Generation) - an AI technique that finds relevant code by understanding meaning rather than matching keywords. It converts code into vector embeddings and uses semantic similarity to retrieve contextually relevant chunks when you ask questions in natural language.

• ~1.5GB disk space for embedding model download
  • Model: google/embeddinggemma-300m (768 dimensions)
  • Downloads automatically on first use (10-30 minutes)
  • Cached at: ~/.claude_code_search/models/
  • One-time download, reused across all projects

Platform Support

✅ Fully Supported:

• macOS (Intel + Apple Silicon)
  • Apple Silicon: Tested on M1/M2/M3 chips - semantic search works perfectly with MPS (Metal Performance Shaders) GPU acceleration
  • Model loads on mps:0 device for optimal performance
• Linux (x86_64, ARM64)
• Windows (via WSL)

Index Type: Uses IndexFlatIP (FAISS) - simple, reliable, cross-platform compatible

Installation

Choose one installation method based on your needs:

📋 Quick Decision Guide:

Option 1: Project Skills (Recommended)

Use Case: Add multi-agent research, planning, and semantic search to an existing Claude Code project.

How It Works: Claude Code auto-discovers skills in .claude/skills/ directory. No manual configuration needed.

# Navigate to your existing project
cd ~/my-existing-project

# Clone into .claude/skills/ directory
mkdir -p .claude/skills
cd .claude/skills
git clone https://github.com/ahmedibrahim085/Claude-Multi-Agent-Research-System-Skill.git

Optional: Enable semantic-search skill

Note: The multi-agent-researcher and spec-workflow-orchestrator skills work immediately. Only install if you want semantic code search.

# Clone Python library to standard location (one-time, 30 seconds)
git clone https://github.com/FarhanAliRaza/claude-context-local.git ~/.local/share/claude-context-local

That's it! Start Claude Code in your project:

cd ~/my-existing-project
claude

The SessionStart hook will automatically initialize all skills.

Optional: Import Orchestration Rules

If you want to use this project's orchestration rules (auto-skill-activation hooks) in your existing project:

# Add to your project's .claude/CLAUDE.md
@import .claude/skills/Claude-Multi-Agent-Research-System-Skill/.claude/CLAUDE.md

This imports the trigger keyword system that auto-activates skills based on your requests (e.g., "research X" → multi-agent-researcher, "plan feature Y" → spec-workflow-orchestrator).

Option 2: Personal Skills

Use Case: Make skills available to all your Claude Code projects (system-wide installation).

How It Works: Claude Code auto-discovers skills in ~/.claude/skills/ and makes them available to every project.

# Clone into personal skills directory
mkdir -p ~/.claude/skills
cd ~/.claude/skills
git clone https://github.com/ahmedibrahim085/Claude-Multi-Agent-Research-System-Skill.git

# Optional: Enable semantic-search
git clone https://github.com/FarhanAliRaza/claude-context-local.git ~/.local/share/claude-context-local

That's it! Skills are now available in every Claude Code project:

cd ~/any-project
claude
# Skills automatically available

Note: Personal skills don't include project-specific hooks or CLAUDE.md rules. You'll need to manually invoke skills using the Skill tool or add @import statements to individual projects.

Option 3: Standalone Usage

Use Case: Explore this repository as a dedicated research/planning workspace.

git clone https://github.com/ahmedibrahim085/Claude-Multi-Agent-Research-System-Skill.git
cd Claude-Multi-Agent-Research-System-Skill

# Optional: Enable semantic-search
git clone https://github.com/FarhanAliRaza/claude-context-local.git ~/.local/share/claude-context-local

# Start Claude Code
claude

Full Experience: This option includes:

• All 3 skills (multi-agent-researcher, spec-workflow-orchestrator, semantic-search)
• Auto-activation hooks (trigger keywords automatically invoke skills)
• Pre-configured directory structure
• Session logging and state management
• 4 custom slash commands (/research-topic, /plan-feature, /project-status, /verify-structure)

Common Setup (All Options)

Automatic Initialization: The SessionStart hook runs on every claude command and:

• Auto-reindexes semantic search (smart change detection, 60-min cooldown)
• Creates required directories (files/research_notes/, files/reports/, logs/)
• Initializes session logging
• Checks prerequisites and displays setup status

No Manual Configuration: Hooks are pre-configured in .claude/settings.json and work out-of-the-box.

First-Time Semantic Search: The embedding model (~1.2GB) downloads automatically on first use (10-30 minutes). Subsequent uses are instant. Model cached at ~/.claude_code_search/models/.

Semantic Search Details:

• Imports Python modules from claude-context-local via sys.path.insert()
• No virtual environment, no pip install, no uv needed
• Merkle tree change detection for smart reindexing
• Multi-language code chunking (15+ languages)
• Embedding generation (sentence-transformers, FAISS)

License Note: claude-context-local is GPL-3.0. Our project imports it via PYTHONPATH (dynamic linking), preserving our Apache 2.0 license. See docs/architecture/MCP-DEPENDENCY-STRATEGY.md for details.

Important: Do not duplicate hooks in settings.local.json to avoid duplicate hook executions.

Post-Installation: CLAUDE.md Setup (Options 2 & 3)

For Option 2 (Personal Skills) and when integrating skills into existing projects, add the following to your project's .claude/CLAUDE.md to help Claude understand the available skills:

## Multi-Agent Research System Skills

This project has access to 3 specialized skills with hook-based auto-activation:

| Skill | Purpose | Trigger |
|-------|---------|---------|
| multi-agent-researcher | Research requiring 2+ sources, synthesis | "research...", "investigate..." |
| spec-workflow-orchestrator | Feature planning, specs, ADRs | "plan...", "design...", "spec..." |
| semantic-search | Find code by meaning, not keywords | "find...", "where is...", "how does..." |

**Usage**: Skills auto-activate via hooks when trigger keywords detected.
Manual invocation: Use `/research-topic`, `/plan-feature`, or `/semantic-search`.

**Documentation**: See skill SKILL.md files for detailed workflows.

Automated Setup: Run python3 setup.py --repair to automatically add skill instructions to your project's CLAUDE.md.

Fresh Clone Quick Start

If you already have semantic-search prerequisites from another project: