# Level 1: BM25 only (fast, 0 AI deps, works everywhere)
uv tool install git+https://github.com/Mavis2103/skill-context-manager

# Level 2: + Embedding search with all-MiniLM-L6-v2 (recommended)
uv tool install 'git+https://github.com/Mavis2103/skill-context-manager[light]'

# Level 3: + Full reranker (cross-encoder) for best accuracy
uv tool install 'git+https://github.com/Mavis2103/skill-context-manager[full]'

scm --version
scm mcp setup --all                 # MCP config for all 13 agent platforms
scm index                           # auto-detect skill dirs
# Or point at a specific directory:
scm index --dir ~/.hermes/skills/

# Reinstall from GitHub to get latest (keeps same extra: light/full if any)
uv tool install --reinstall 'git+https://github.com/Mavis2103/skill-context-manager[light]'

scm mcp setup --force-all --uninstall   # clean MCP configs first
uv tool uninstall scm                   # remove tool + venv
rm -rf ~/.scm                           # remove database

git clone https://github.com/Mavis2103/skill-context-manager.git
cd skill-context-manager
uv venv && source .venv/bin/activate
uv pip install -e .                   # Level 1: BM25 only
# or: uv pip install -e ".[light]"    # Level 2: + embedding (recommended)
# or: uv pip install -e ".[full]"     # Level 3: + reranker

# Auto-detect — finds all agent skill dirs installed on this system
# (~/.agents/skills/, ~/.hermes/skills/, ~/.claude/skills/, ...)
scm index
# 📂 Scanning ~/.hermes/skills/ for skills...
# ✅ Indexed 47 skill files

# Or point at any directory (safe — skips .git, node_modules, .venv, __pycache__,
# dist, all hidden dirs, and more)
scm index --dir ~/my-skills/

# Scan full home safely — still skips the same noise dirs
scm index --dir ~/

# Progress shown automatically for large scans:
#    ... scanned 100/150
#    ✅ Indexed 150 skill files

# BM25 (FTS5) — stdlib only, fast, precise for keywords
scm query "kubernetes deploy helm" --method bm25

# Embedding — semantic search (requires sentence-transformers)
scm query "orchestrate container cluster management" --method embedding

# Hybrid (default) — best of both worlds
scm query "deploy app to production" --method hybrid

scm session start --id "chat-abc-123"
scm session use --skill k8s-deploy --query "deploy"
scm session use --skill docker-build --query "build image"

# Export context for the agent — only ~30 tokens
scm session context --id "chat-abc-123"

# Output:
# {
#   "active_skills": ["k8s-deploy", "docker-build"],
#   "context_size_tokens": 42,
#   "matching_skills": [...]
# }

# Record feedback
scm feedback record --query "deploy app" --skill k8s-deploy --success true --rating 5
scm feedback record --query "deploy app" --skill helm --success false

# View statistics
scm feedback stats
# 📊 Feedback Statistics
#    Total feedback:     47
#    Success rate:       87%
#    Query patterns:     12
#    Skills with data:   8
#    Top skills by success rate:
#      • k8s-deploy: 15/16 (94%)
#      • docker-build: 8/10 (80%)

# Preview
scm optimize --dir ~/.hermes/skills/ --dry-run
# 📊 Potential savings:
#    Before: 1,847 meta tokens
#    After:  1,240 meta tokens
#    Saved:  607 tokens per load (33%)

# Apply
scm optimize --dir ~/.hermes/skills/ --no-dry-run

scm insights
# 📈 Usage Insights (last 30 days)
#    Total queries:     142
#    Tokens saved:      ~28,400
#    Retrieval methods: bm25: 89, hybrid: 42, embedding: 11
#    Top skills used:
#      • k8s-deploy: 23 times
#      • pytest-run: 18 times
#      • docker-build: 15 times

scm stats
# 📊 Skill Index Statistics
#    Total skills:     24
#    Categories:       5
#    Metadata tokens:  1,847
#    Body tokens:      12,430

User Request
    │
    ▼
┌─────────────────────────────────────────────────┐
│ 1. Query Analysis                               │
│    - Extract key terms                          │
│    - Embed query (if embedding enabled)         │
└─────────────────────┬───────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────┐
│ 2. Stage 1: Retrieval (top 20)                   │
│    ┌──────────┐   ┌──────────┐   ┌──────────┐   │
│    │  BM25    │ + │Embedding │ = │  Hybrid  │   │
│    │ (FTS5)   │   │ (cosine) │   │ (0.3+0.7)│   │
│    └──────────┘   └──────────┘   └──────────┘   │
└─────────────────────┬───────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────┐
│ 3. Context Injection                             │
│    + Session boost (recently used +0.5)          │
│    + Feedback weights (Bayesian prior)           │
└─────────────────────┬───────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────┐
│ 4. Stage 2: Rerank (top 5)                       │
│    Cross-encoder: query × skill body             │
│    "cross-encoder/ms-marco-MiniLM-L6-v2"         │
│    ~50ms on CPU for 20 candidates                │
└─────────────────────┬───────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────┐
│ 5. Output                                        │
│    - Top 5 skill names + descriptions (~300 t)   │
│    - Session context (~30 tokens)                │
│    - Agent loads only the 1 skill body it needs  │
└─────────────────────────────────────────────────┘

Without SCM:
  Session start: load 50 skills metadata = 50 × 60 tokens = 3,000 tokens
  Agent picks 1, but ALL 50 stay in context
  Session grows → agent forgets → re-load all: +3,000 tokens
  Total waste: ~6,000+ tokens per session

With SCM:
  Session start: active skills only = 3 × 15 tokens = 45 tokens
  Query → top 5 metadata = 5 × 40 tokens = 200 tokens
  Session tracker: ~30 tokens
  Total: ~275 tokens per query
  Savings: 85-98%

# Configure for ALL supported agents at once
scm mcp setup --all

# Or pick specific agents
scm mcp setup --claude-code --cursor --windsurf --hermes

# Remove SCM config from all agents
scm mcp setup --all --uninstall

# List all supported platforms with their config paths
scm mcp setup --list

# Check which agents have SCM configured
scm mcp status

# Output (example):
# SCM MCP Status
#   ✅ Claude Code: Configured
#   ✅ Cursor: Configured
#   ○ Windsurf: Config exists, not configured
#   · Zed: Config not found

# Auto-configure for all agents (idempotent)
scm mcp setup --all

# Check configuration status
scm mcp status

# Start server in stdio mode (default)
python3 -m scm.mcp_server

# Start server in HTTP/SSE mode
python3 -m scm.mcp_server --http --port 8321

mcp_servers:
  scm:
    command: python3
    args: ["-m", "scm.mcp_server"]
    allowed_tools:
      - skill_query
      - skill_session_start
      - skill_session_use
      - skill_session_context
      - skill_session_end
      - skill_feedback
      - skill_feedback_stats
      - skill_stats
      - skill_insights

hermes mcp test scm
# ✓ Connected (738ms)
# ✓ Tools discovered: 11

{
  "mcp": {
    "scm": {
      "type": "local",
      "command": ["python3", "-m", "scm.mcp_server"],
      "enabled": true
    }
  }
}

{
  "mcpServers": {
    "scm": {
      "command": "python3",
      "args": ["-m", "scm.mcp_server"]
    }
  }
}

{
  "servers": {
    "scm": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "scm.mcp_server"]
    }
  }
}

[mcp_servers.scm]
command = "python3"
args = ["-m", "scm.mcp_server"]

# Start server
python3 -m scm.mcp_server --http --port 8321

# Client config
{
  "mcpServers": {
    "scm": {
      "url": "http://localhost:8321/sse"
    }
  }
}

---
name: skill-router
description: Select and load the most relevant agent skills using semantic search
---

When a skill needs to be selected for a task, use:
  scm query "<user_task>" --top 3 --format json
Then load the SKILL.md body of the top-matching skill.

skill-context-manager/
├── src/scm/
│   ├── __init__.py          # Version + schema init
│   ├── cli.py               # CLI interface (argparse, 9 subcommands)
│   ├── db.py                # Shared database connection (single DB, WAL)
│   ├── indexer.py           # Skill indexing engine (FTS5)
│   ├── retriever.py         # BM25 + embedding retrieval
│   ├── reranker.py          # Cross-encoder reranking
│   ├── session.py           # Session state tracker
│   ├── optimizer.py         # Skill metadata optimizer
│   ├── feedback.py          # Feedback collection + Bayesian learning
│   ├── tracker.py           # Usage analytics
│   ├── models.py            # Data models (Skill, QueryResult, SessionState, FeedbackRecord)
│   └── mcp_server.py        # MCP server (11 tools)
│   └── mcp_setup.py         # Multi-agent MCP setup registry (13 platforms)
├── tests/
│   ├── test_models.py       # 14 tests — data models + YAML parsing + unquoted colon
│   ├── test_indexer.py      # 19 tests — index/reindex/skip/detect/progress/WAL
│   ├── test_retriever.py    # 10 tests — BM25/embedding/RRF/hybrid/session/graph boost/empty
│   ├── test_adaptive.py     # 20 tests — elbow detection/DBSCAN clustering/diverse/adaptive query
│   ├── test_graph.py        # 7 tests — graph edges/PPR/graph boost
│   ├── test_session_feedback.py  # 21 tests — session lifecycle + feedback
│   ├── test_optimizer.py    # 9 tests — compression/expansion/info-leak
│   ├── test_tracker.py      # 8 tests — recording/insights/daily-trend
│   ├── test_reranker.py     # 6 tests — fallback/empty/top-k/custom model
│   ├── test_mcp_setup.py    # 26 tests — multi-agent registry (13 platforms)
│   └── test_regression.py   # 24 tests — bug regression coverage
├── scripts/
│   ├── benchmark.sh         # Performance benchmark
│   └── demo.sh              # Interactive demo
├── configs/
│   └── default.yaml         # Default configuration
├── docs/
│   ├── ARCHITECTURE.md      # Detailed architecture docs
│   └── MCP-INTEGRATION.md   # MCP integration guide
├── pyproject.toml
├── LICENSE
└── README.md

User: "Deploy app to production"

Agent internally calls:
  → skill_query(query="deploy app to production", top_k=3)
  → Returns: [kubernetes-deploy (0.92), docker-build (0.78), monitoring (0.45)]
  → Agent loads kubernetes-deploy SKILL.md, executes deploy steps
  → skill_session_use(session_id="...", skill_name="kubernetes-deploy", success=true)

Agent generates system prompt block:
  "Session active skills: [kubernetes-deploy]
   Related skills: [docker-build, helm-chart]
   Estimated context: 15 tokens"

# This query doesn't need to scan all skills again.
# Session tracker knows kubernetes-deploy was used and boosts it.
# Saves 50-200 tokens per query.
scm session context --id "..." --query "scale deployment"

# All 168 tests
uv run pytest -v

# Specific module
uv run pytest tests/test_indexer.py -v

# Just regression tests
uv run pytest tests/test_regression.py -v

# Coverage (optional)
uv run pytest --cov=src/scm/ tests/

# SCM auto-migrates schema on version changes (CREATE TABLE IF NOT EXISTS)
# No manual migration needed