convez.ai
MCP ServerAutomaçãoAvançado
ccancellieri

MCP Skill Hub

ccancellieri/mcp-skill-hub

Busca semântica de skills + execução local offline para Claude Code

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP local que otimiza Claude Code através de busca semântica de skills, intercepção de hooks sem tokens e engine de execução local em 4 níveis. Reduz consumo de tokens em até 80%, funciona offline com Ollama e aprende o vocabulário do usuário ao longo do tempo.

Instalação

$npx convez-ai ccancellieri/mcp-skill-hub

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
6
Contribuidores
1

Casos de uso

  • Otimizar contexto ao usar múltiplos plugins no Claude Code
  • Executar comandos de tarefas localmente sem consumir tokens da API
  • Implementar execução serverless de skills com fallback offline
  • Aprender e adaptar a busca de skills conforme o padrão de uso

Veredito

Ferramental robusto para arquitetar sistemas Claude com busca semântica local e intercepção inteligente de hooks. Exige conhecimento técnico de MCP, Python e Ollama, mas oferece ganhos reais de custo e latência para fluxos complexos com múltiplos plugins.

README

A tradução para o português deste README ainda está na fila.

MCP Skill Hub

A local MCP server that makes Claude Code smarter, cheaper, and offline-capable. Semantic skill search, zero-token hook interception, and a full 4-level local execution engine — all running on your machine with Ollama.


Why Skill Hub?

Claude Code loads every enabled plugin's skills into your context at session start. With 20+ plugins, that's thousands of wasted tokens on definitions you'll never use. Responses degrade, latency grows, bills rise.

Skill Hub fixes this with three layers that work together:

LayerWhat it doesSaved
🔎 Semantic searchFinds skills by meaning, not keywords — only loads what matters~80% context
🎯 Zero-token hooksTask commands (save task, close task, list tasks) are caught before Claude sees them100% of those tokens
🤖 Local execution (L1–L4)Whitelisted commands → templates → skills → full local agent; all on OllamaAPI calls avoided

Add teaching rules, feedback learning, shadow skill evolution, offline auto-fallback, and a web control panel — and the hub learns your vocabulary over time.


🚀 Quick Start

git clone https://github.com/ccancellieri/mcp-skill-hub.git
cd mcp-skill-hub
./install.sh          # macOS / Linux
python install.py     # cross-platform

The installer pulls a 274 MB embedding model, registers the MCP server, and merges hooks into ~/.claude/settings.json (idempotent — safe to re-run).

Then restart Claude Code and run:

index_skills()      # index all plugin skills
index_plugins()     # index plugin descriptions

👉 Full installation options (SearXNG, remote VPS, model picks per RAM budget): docs/installation.md


🎬 In 30 Seconds

User: "save to memory and close"
         │
    ┌────┴──────────────────┐
    │  UserPromptSubmit     │ ← hook fires BEFORE Claude
    │  Hook                 │
    └────┬──────────────────┘
         │
    ┌────┴──────────────────┐
    │  Local LLM classifies │ ← qwen2.5-coder:7b on your machine
    │  "Is this a task      │
    │   command?"           │
    └────┬──────────────────┘
         │
    YES: execute locally           NO: pass through
    save_task() / close_task()     → Claude processes normally
    return {"decision":"block"}
         │
    0 Claude tokens used

✨ Feature Highlights

🔎 Semantic Search

Describe the task in natural language — get matching skills ranked by cosine similarity + your feedback history.

search_skills("debug failing pytest")

→ docs/features/semantic-search.md

🎯 Zero-Token Hooks

Task commands are intercepted before Claude. Each interception saves 300–800 tokens.

"save this as task"      →  0 tokens
"list my open tasks"     →  0 tokens
"what was I working on?" →  0 tokens

→ docs/features/hooks.md

🤖 Local Execution

4 escalating levels: whitelisted commands → templates → multi-step skills → full L4 agent loop.

L1: "git status"
L2: "show last 5 commits"
L3: "project summary"  (4-step skill)
L4: "run tests and summarize"

→ docs/features/local-execution.md

🧠 Learning

Teaching rules, feedback EMA, session history, shadow evolution — the hub gets measurably smarter over time. → docs/features/learning.md

🖥️ Web Control Panel

FastAPI suite at http://localhost:8765/control — start/stop Ollama, SearXNG, models; live RAM/CPU pressure; plugin toggles; profile switching. → docs/features/web-control-panel.md

🧭 Offline & Fallback

TCP probes Anthropic every 30 s. Unreachable? L4 agent silently takes over. Rate-limited? Exhaustion-save compacts your session. → docs/features/local-execution.md#offline--exhaustion

🗂️ Session Profiles

Swap entire plugin sets per context: minimal, backend, frontend, mcp-dev, data, full — or save your own. → docs/features/profiles.md

🪶 Context Bridge

Captures Claude's tool calls in real-time → {session_context}, {tool_examples}, {repo_context} injected into every local skill. → docs/advanced/context-bridge.md

🎓 Fine-Tuning

Export JSONL training data from your own feedback, triage, and compact history. Fine-tune on Apple Silicon via mlx-lm. → docs/advanced/fine-tuning.md


📚 Documentation

Everything lives in docs/. Start with the index below — it's kept in sync with code.

🧭 Documentation Index →

AreaDocWhen to read
Getting Startedinstallation.mdFirst install, model picks, SearXNG, remote VPS
Featuresweb-control-panel.mdManage services + plugins from a browser
semantic-search.mdsearch_skills, search_context, tasks, digest
hooks.mdHow zero-token interception + context injection work
learning.mdTeachings, feedback, implicit learning, evolution
local-execution.mdL1–L4, offline fallback, exhaustion save, triage
profiles.mdPlugin profile packs + auto-recommendation
utilities.mdExtra skill dirs, status, resource gating, REPL, tooltips
Referencereference/tools.mdEvery MCP tool + CLI command
reference/config.mdAll config keys, defaults, description
reference/architecture.mdSource layout, dual skill index, output paths
reference/database.mdSQLite schema + table purposes
reference/logs.mdLog streams, common issues, troubleshooting
Advancedadvanced/skill-chaining.mdLocal skill branching, labels, agent type
advanced/context-bridge.mdHow Claude's tool calls flow into local skills
advanced/fine-tuning.mdExporting JSONL, training with mlx-lm
Opsunattended.mdRun Claude Code overnight without prompts
plugin-extension-points.mdHow third-party plugins extend Skill Hub
roadmap.mdShipped milestones + what's next

🏃 Common Workflows

# Search past work
search_context("accessibility audit for a website")

# Save & close tasks (zero Claude tokens via hooks)
save_task(title="MCP skill hub dev", summary="Building semantic search…")
close_task(task_id=1)    # compacts to ~200 tokens, writes memory entry

# Master State compaction (folds task auto-memory into project's decisions.md)
compact_master_state(project_root="~/work/code/geoid", dry_run=True)
# After preview + approval:
compact_master_state(project_root="~/work/code/geoid")
# Or wire into close_task:
close_task(task_id=1, compact_master_state=True)

# Teach the hub
teach(rule="when I give a URL", suggest="chrome-devtools-mcp")

# Switch profiles
/profile backend
/profile auto build MCP server

# Check token savings
token_stats()   # → e.g. "52,300 tokens saved across 89 interceptions"

🌳 Worktree-Driven Parallel Sessions

Spawn a Claude session inside an isolated git worktree as part of saving a task, and resume it later — the worktree outlives the task by default.

# Cold start from a non-repo dir like ~/work/code/
cwt geoid es-pr2c                              # opens iTerm tab in a fresh worktree
cwt geoid swarm-3 --mode background            # headless agent, output to logfile
cwt --resume 47                                # focus alive session, or relaunch
cwt --list                                     # open tasks + worktree liveness

From inside Claude (auto-saves the task and spawns the session):

save_task("ES PR-2c retarget", "...", project="geoid", mode="terminal")
reopen_task(47)                                # alive → focus, dead → relaunch
close_task(47, remove_worktree=True)           # also tears down the worktree

Layout:

  • Worktree: <repo>/.claude/worktrees/<slug> (per-repo, gitignored)
  • Branch: cc/<slug> (local-only convention for AI-tooling work)
  • Liveness: <worktree>/.claude/session.pid (cleaned up by a Stop hook)

Modes: terminal (macOS iTerm/Terminal tab), tmux (window in $TMUX), background (headless claude --print to a logfile).

Config (~/.claude/mcp-skill-hub/config.json):

{
  "worktree": {
    "repo_roots": ["~/work/code"],
    "default_mode": "terminal"
  }
}

/team — specialized orchestration

Skill Hub is the intelligence layer on top of Claude Code's native agent primitives — subagents, agent teams, and the Workflow tool. It does not re-implement orchestration; it supplies specialized role definitions, a model·effort policy, and an upfront prompt-refactor step, then delegates execution entirely to the native substrate. The /team command is the single entry point for all of this.

Before spawning a single agent, /team calls improve_prompt to sharpen the working brief. It then calls team_plan to resolve the full roster: which agent types run, at what model tier, in what order, with how many verification loops. The roster is deterministic given (kind, effort) — pass --estimate to see it without executing anything.

/team <kind>Task shapeSubstrateNotes
reviewadversarial — 4 lens reviewers challenge each otheragent teamrequires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1; falls back to parallel subagents
archadversarial — competing hypotheses + devil's-advocate debateagent teamsame fallback
issuesdeterministic triage pipelineWorkflow toolfetch → classify → draft; resumable; cheap
implementdeterministic build pipelineWorkflow tooldesign → build → verify → clean → PR

The --effort flag sets both the model floor and the number of verification loops (default xhigh):

EffortModel floorVerification loops
lowhaiku / sonnet0
mediumsonnet1
highsonnet / opus2
xhigh (default)opus3

Accuracy-critical roles (team-arch-analyst, team-reviewer, team-human-voice-writer) reach Opus at xhigh. Mechanical roles (team-code-implementer, team-mechanical-refactorer, team-github-operator) cap at sonnet or haiku — they do not need Opus-level judgement.

The six agent types and their assignments:

  • team-arch-analyst (opus) — read-only deep architecture and code analysis; cites file:line; never edits
  • team-reviewer (opus at xhigh) — adversarial review; refute-by-default; severity ratings
  • team-code-implementer (sonnet) — implements a clear spec following existing patterns; no scope creep
  • team-mechanical-refactorer (sonnet) — behavior-preserving rename/simplify; smallest diff
  • team-human-voice-writer (opus) — first-person engineer prose; no AI attribution, no emoji, no "recommendations" tables
  • team-github-operator (haiku) — gh inspect/fetch/triage/post; posts only pre-written prose, never authors it
/team review 142                                  # adversarial 4-lens review of PR 142
/team arch src/skill_hub/router                   # architecture analysis with devil's advocate
/team issues mcp-skill-hub label:bug --estimate   # preview triage plan + cost, no execution
/team implement 49 --effort high                  # build pipeline, high effort (2 verify loops)

🔧 Requirements

  • Python 3.10+, Ollama, ~5 GB disk for models (more for larger reasoning models)
  • macOS / Linux / Windows — cross-platform installer picks the right hooks
  • Optional: Docker (for SearXNG), remote Ollama VPS (offload heaviest model)

📄 License

Copyright © 2026 Carlo Cancellieri — Licensed under the Apache License 2.0. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados