skilljit

面向 Claude 的即时技能与 MCP 工具路由——以一份 token 的成本安装数千个技能。在任务真正需要之前，没有任何内容加载到上下文中。

为什么工具列表永远不会变化

按需添加工具的显而易见的方式是 MCP 的 notifications/tools/list_changed 通知。它在 Claude Desktop 中已损坏—— anthropics/claude-code#50339 记录了它在 336+ 个版本中被忽略（空的客户端能力、从不触发的 SDK 处理器、冻结的工具列表引用），并且 Anthropic 将该问题关闭为不计划修复。该问题自身推荐的变通方案是*“在启动时声明所有工具，并通过模式/操作参数在内部进行分发。”*

这正是 skilljit 所做的。它的 MCP 工具列表是固定的，永远不会改变——始终是一小撮恒定数量的工具。技能和上游 MCP 工具是通过这些工具被发现和加载的，而不是通过重新注册工具列表。这就是为什么 skilljit 能在 Claude Desktop、Claude Code、Codex 和 Cursor 上正常工作，而基于 list_changed 的代理在至少其中一个上会静默降级。

Related MCP server: MCPNexus

问题

Claude 的 Agent Skills 使用渐进式披露：每个技能的 name + description（约 100 个 token）在每一轮对话中都位于系统提示中，只有正文按需加载。这在 10 个技能时有效。在规模扩大时就会崩溃——生态系统已经存在，数千个仓库中有数万个技能。安装 200 个技能，每轮对话就要花费数万个 token，而且永远如此。所以没有人这样做——每个人都安装十个，其余的都不可达。

MCP 有完全相同的问题，而且更糟：每个已连接服务器的完整工具模式在启动时加载，通常在用户输入任何内容之前就有 20k–50k 个 token。

安装

npx -y skilljit sync

这是主要路径——MCP 生态系统以 npx 为先，Claude Code / Desktop 配置已经期望这种形态。

还发布了一个轻量级 Python 配套包，供希望直接查询同一目录而不是通过 MCP 的 claude-agent-sdk 用户使用：

pip install skilljit

参见 python/README.md 了解该包能做什么和不能做什么 ——它将 CLI 转发到 npx -y skilljit，并为 Python 添加了一个只读的 Catalog。

Node 版本支持

skilljit、@skilljit/mcp 和 @skilljit/proxy 需要 Node 18+——这个下限直接来自 @modelcontextprotocol/sdk，MCP 服务器和代理层依赖它，而它本身要求 18+。除非放弃 MCP 支持，否则无法绕过这一点。

@skilljit/core（目录/搜索库，无 MCP 依赖）支持 Node 16+，适用于直接使用其 Catalog/ingestGithubRepo API 的用户。在 Node 18+ 上，这是零编译安装（better-sqlite3 附带预编译二进制文件）。在 Node 16/17 上，better-sqlite3 在任何平台上都没有针对该 ABI 的预编译二进制文件，因此 npm 会通过 node-gyp 回退到从源代码编译——这需要 C++ 工具链和带有（3.12 之前的）distutils 模块的 Python。这是原生 Node 模块的标准要求，不是 skilljit 特有的步骤，但这确实意味着 Node 16/17 安装 @skilljit/core 不能保证像 18+ 那样零摩擦。

快速开始

# 1. Build the local catalog from GitHub sources (SQLite, ~/.skilljit/catalog.db)
skilljit sync

# 2. Search it — no network call, no context cost
skilljit search "postgres migration"

# 3. Point your MCP client at the server
skilljit serve

添加到你的 MCP 客户端配置（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "skilljit": {
      "command": "npx",
      "args": ["-y", "skilljit", "serve"]
    }
  }
}

其他命令：skilljit stats（目录大小 + 如何读取实时节省量）、 skilljit init <configPath>（预览将你现有的 MCP 服务器路由到 skilljit——绝不修改原始文件）、skilljit adopt <configPath>（应用它）、skilljit doctor [configPath]（验证上游仍然工作）、skilljit restore <configPath>（撤销 adopt）。

将你自己的技能添加到 sync

默认情况下，sync 只从一小撮精选的公共仓库中拉取。要添加你自己的：

# Another public (or your-token-authenticated private) GitHub repo:
skilljit sync --repo your-org/internal-skills --token "$SKILLJIT_GITHUB_TOKEN"

# Any git remote at all — self-hosted, GitLab, Bitbucket, or a private repo
# reached over SSH — using whatever git credentials are already set up on
# this machine. No GitHub API token needed for this path.
skilljit sync --git git@git.internal.example.com:team/skills.git

两个标志都可以重复。--git 源通过裸镜像克隆加 git worktree 而不是 GitHub API 进行摄取：第一次同步支付完整克隆的费用，之后的每次同步都是廉价的 git fetch + worktree 检出——没有速率限制，没有令牌，适用于 git 本身可以访问的任何内容。

六个工具

skilljit 暴露了一个固定的表面——它在运行时永远不会增长或缩小。

skill_find → skill_load → skill_read_file 是重建为拉取的渐进式披露，一直到底部：始终加载的成本不再随目录大小扩展，并且技能捆绑的参考文档/脚本在按路径命名之前不会进入上下文，即使在技能本身已加载之后也是如此。

tool_find 和 tool_call 只有在你通过 skilljit adopt（见下文）配置了上游 MCP 服务器后才会出现——仅运行技能时，表面是 4 个工具，而不是 6 个。这就是使技能半部分可以独立于代理半部分发布和测试的原因。

多个标签页 / 并行会话

同时运行多个 Claude Code 标签页处理不同任务，正是“每个标签页为每个已安装技能付费”的成本成倍增加的地方——打开 N 个标签页意味着每轮开销同时支付 N 次。skilljit 已经将该每标签页成本压缩为固定的几个工具，无论目录大小如何，但 skilljit_stats() 更进一步：每个会话的基线/实际数字也会写入共享的 catalog.db（每个标签页的 skilljit serve 进程已经指向的同一个文件），因此报告的总数是跨你打开过的每个标签页的累计值，而不仅仅是你正在询问的那个。丢失一个标签页不会丢失该数字——它已经被持久化写入，而不是仅保存在该标签页的内存中。

这不会恢复丢失标签页的对话本身——那是 Claude Code 会话功能（claude --resume / --continue），与 skilljit 无关。它专门修复的是 token 核算的盲点：“skilljit 今天实际上为我节省了多少，跨我打开的所有内容”，即使任何一个标签页死亡也能幸存。

MCP 代理——路由你的其他 MCP 服务器

传递 skilljit serve --config <path>（你之前运行 skilljit adopt 的配置路径）会为它采用的服务器启用 tool_find/tool_call。这里安全第一，因为它涉及你已经依赖的配置：

• skilljit init <configPath> 绝不修改原始文件——它写入一个建议的配置并打印差异。

• skilljit adopt <configPath> 默认是试运行；传递 --yes 才实际写入更改，并备份原始文件。

• --keep server1,server2 使这些服务器保持不变——在静态工具列表中完全可见，无需 tool_find 往返。适用于你每轮都调用的热路径工具。（在此版本中，Keep 是按服务器而不是按工具。）

• skilljit doctor [configPath] 验证每个被采用的上游仍然能启动、握手并列出工具。

• skilljit restore <configPath> 是一条命令，将原始配置放回。

• 一个上游 MCP 服务器不可用不会影响其他服务器：tool_call 为该服务器返回一个干净的错误，其他一切继续工作。

安全

技能在功能上是陌生人提供的指令，代理会遵循——Anthropic 明确警告恶意技能可以窃取数据或滥用工具。skilljit 将其视为需要设计的功能，而不是事后考虑：

• 每个 skill_find 结果都会在描述旁边显示技能的审计状态。

• 当技能未通过审计或根本未审计时，skill_load 会在返回的内容中大声警告——与从未知来源安装软件相同的姿态。

基准测试

bench/ 附带一组标记的 41 个 (任务 → 正确技能) 对和一个 recall@k 测试框架，因此“搜索有效”是一个可测量的声明，而不是一种感觉。当前数字，可通过 node bench/run.mjs 重现：

skilljit bench — 41 queries over 41 skills

recall@1: 37/41  (90.2%)
recall@3: 38/41  (92.7%)
recall@8: 41/41  (100.0%)

搜索是 SQLite FTS5 + BM25——v1 中没有嵌入。这是一个刻意的 YAGNI 决定：FTS5 在 Node（better-sqlite3）和 Python（标准库）实现中完全相同地提供，无需模型下载或额外的运行时依赖。残余的召回风险（技能描述是语义性的——“当用户提到 PDF 时使用……”）在结构上得到缓解：skill_find 返回多个候选供 Claude 考虑和重新查询，而不是承诺一次性 top-1 结果。嵌入保持为可选选项，仅在此基准测试显示 FTS5 召回确实不足时才添加——上面的三个未命中（都是接近命中，正确技能刚好在前 3 名之外）是该决定的具体候选。

发布

推送 v* 标签（例如 v0.1.2）会运行 CI，然后通过 Trusted Publishing (OIDC) 将每个包发布到 npm 和 PyPI——此仓库中没有长期存在的 NPM_TOKEN/PYPI_TOKEN 秘密。参见 .github/workflows/release.yml。

在此之前需要一次性设置，手动完成（无法自动化）：

• 在 npmjs.com 上，为 @skilljit/core、@skilljit/proxy、@skilljit/mcp 和 skilljit 各注册一个 Trusted Publisher，指向此仓库、release.yml 工作流文件和 npm 环境。

• 在 pypi.org 上，为 skilljit 项目注册一个 Trusted Publisher，指向此仓库、release.yml 工作流文件和 pypi 环境。

架构

skilljit/
  packages/core/     catalog store, FTS5 index, ranking, token accounting
  packages/proxy/    upstream MCP server management, config adopt/restore, tool_find/tool_call routing
  packages/mcp/      the MCP stdio server (the fixed tool surface, see "The six tools" above)
  packages/cli/      skilljit sync | search | serve | stats | init | adopt | restore | doctor
  python/            pip package — CLI shim + read-only query API for Agent SDK users
  bench/             labeled task→skill eval set + recall@k harness

TypeScript 是唯一实现；PyPI 包是围绕它的一个轻量、诚实的包装器，而不是排名逻辑的第二个实现。

许可证

MIT