MCP Skill Hub
ccancellieri/mcp-skill-hub
Busca semântica de skills + execução local offline para Claude Code
Ver no GitHubServidor 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-hub1 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
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:
| Layer | What it does | Saved |
|---|---|---|
| 🔎 Semantic search | Finds skills by meaning, not keywords — only loads what matters | ~80% context |
| 🎯 Zero-token hooks | Task commands (save task, close task, list tasks) are caught before Claude sees them | 100% of those tokens |
| 🤖 Local execution (L1–L4) | Whitelisted commands → templates → skills → full local agent; all on Ollama | API 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
🤖 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 →
| Area | Doc | When to read |
|---|---|---|
| Getting Started | installation.md | First install, model picks, SearXNG, remote VPS |
| Features | web-control-panel.md | Manage services + plugins from a browser |
| semantic-search.md | search_skills, search_context, tasks, digest | |
| hooks.md | How zero-token interception + context injection work | |
| learning.md | Teachings, feedback, implicit learning, evolution | |
| local-execution.md | L1–L4, offline fallback, exhaustion save, triage | |
| profiles.md | Plugin profile packs + auto-recommendation | |
| utilities.md | Extra skill dirs, status, resource gating, REPL, tooltips | |
| Reference | reference/tools.md | Every MCP tool + CLI command |
| reference/config.md | All config keys, defaults, description | |
| reference/architecture.md | Source layout, dual skill index, output paths | |
| reference/database.md | SQLite schema + table purposes | |
| reference/logs.md | Log streams, common issues, troubleshooting | |
| Advanced | advanced/skill-chaining.md | Local skill branching, labels, agent type |
| advanced/context-bridge.md | How Claude's tool calls flow into local skills | |
| advanced/fine-tuning.md | Exporting JSONL, training with mlx-lm | |
| Ops | unattended.md | Run Claude Code overnight without prompts |
| plugin-extension-points.md | How third-party plugins extend Skill Hub | |
| roadmap.md | Shipped 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 shape | Substrate | Notes |
|---|---|---|---|
review | adversarial — 4 lens reviewers challenge each other | agent team | requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1; falls back to parallel subagents |
arch | adversarial — competing hypotheses + devil's-advocate debate | agent team | same fallback |
issues | deterministic triage pipeline | Workflow tool | fetch → classify → draft; resumable; cheap |
implement | deterministic build pipeline | Workflow tool | design → build → verify → clean → PR |
The --effort flag sets both the model floor and the number of verification loops (default xhigh):
| Effort | Model floor | Verification loops |
|---|---|---|
low | haiku / sonnet | 0 |
medium | sonnet | 1 |
high | sonnet / opus | 2 |
xhigh (default) | opus | 3 |
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) —
ghinspect/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.