skilljit

Enrutamiento justo a tiempo de skills y herramientas MCP para Claude: instala miles de skills al costo de tokens de una sola. Nada se carga en el contexto hasta que una tarea realmente lo necesita.

Por qué la lista de herramientas nunca cambia

La forma obvia de añadir herramientas bajo demanda es la notificación MCP notifications/tools/list_changed. Está rota en Claude Desktop: anthropics/claude-code#50339 documenta que se ignora en más de 336 versiones (capacidades de cliente vacías, un handler del SDK que nunca se dispara, una referencia congelada de la lista de herramientas) y Anthropic cerró el issue como no planificado. La solución recomendada por el propio issue es "declarar todas las herramientas al inicio y despachar internamente mediante parámetros de modo/acción".

Eso es lo que hace skilljit. Su lista de herramientas MCP es fija y nunca cambia: un puñado pequeño y constante de herramientas, siempre. Las skills y las herramientas MCP de terceros se encuentran y cargan a través de esas herramientas, no re-registrando la lista de herramientas. Por eso skilljit funciona en Claude Desktop, Claude Code, Codex y Cursor, mientras que los proxies basados en list_changed se degradan silenciosamente en al menos uno de ellos.

Related MCP server: context-saver

El problema

Las Agent Skills de Claude usan divulgación progresiva: el name + description de cada skill (~100 tokens) está en el prompt del sistema en cada turno, y solo el cuerpo se carga bajo demanda. Eso funciona con 10 skills. Se colapsa a escala: el ecosistema ya está ahí, con decenas de miles de skills en miles de repos. Instalar 200 de ellas cuesta decenas de miles de tokens por turno, para siempre. Así que nadie lo hace: todos instalan diez y el resto es inalcanzable.

MCP tiene el mismo problema, peor: los esquemas completos de herramientas de cada servidor conectado se cargan al inicio, comúnmente 20–50k tokens antes de que el usuario escriba nada.

Instalación

npx -y skilljit sync

Ese es el camino principal: el ecosistema MCP es primero-npx, y las configuraciones de Claude Code / Desktop ya esperan esta forma.

También se publica un compañero Python ligero para los usuarios de claude-agent-sdk que quieran consultar el mismo catálogo directamente en lugar de pasar por MCP:

pip install skilljit

Consulta python/README.md para ver qué hace y qué no hace ese paquete: reenvía el CLI a npx -y skilljit y añade un Catalog de solo lectura para Python.

Soporte de versiones de Node

skilljit, @skilljit/mcp y @skilljit/proxy requieren Node 18+: ese mínimo viene directamente de @modelcontextprotocol/sdk, del que dependen el servidor MCP y la capa de proxy, y que a su vez requiere 18+. No hay forma de evitarlo sin eliminar el soporte MCP.

@skilljit/core (la librería de catálogo/búsqueda, sin dependencia MCP) soporta Node 16+ para cualquiera que use su API Catalog/ingestGithubRepo directamente. En Node 18+ es una instalación sin compilación (better-sqlite3 incluye un binario precompilado). En Node 16/17, better-sqlite3 no tiene binario precompilado para ese ABI en ninguna plataforma, así que npm recurre a compilarlo desde el código fuente mediante node-gyp: esto necesita un toolchain de C++ y un Python con el módulo distutils (pre-3.12) disponible. Ese es un requisito estándar para módulos nativos de Node, no un paso específico de skilljit, pero sí significa que las instalaciones de @skilljit/core en Node 16/17 no están garantizadas sin fricción como en 18+.

Inicio rápido

# 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

Añade a tu configuración de cliente MCP (por ejemplo, claude_desktop_config.json):

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

Otros comandos: skilljit stats (tamaño del catálogo + cómo leer los ahorros en vivo), skilljit init <configPath> (previsualiza el enrutamiento de tus servidores MCP existentes a través de skilljit — nunca muta el original), skilljit adopt <configPath> (aplícalo), skilljit doctor [configPath] (verifica que los upstreams sigan funcionando), skilljit restore <configPath> (deshace adopt).

Añadir tus propias skills a sync

Por defecto, sync solo extrae de una pequeña lista curada de repos públicos. Para añadir las tuyas:

# 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

Ambas banderas son repetibles. Las fuentes --git se ingieren mediante un clon espejo desnudo más git worktree en lugar de la API de GitHub: el primer sync paga un clon completo, cada sync posterior es un git fetch barato + checkout de worktree — sin límite de tasa, sin token, funciona contra cualquier cosa que git mismo pueda alcanzar.

Las seis herramientas

skilljit expone una superficie fija: nunca crece ni se reduce en tiempo de ejecución.

skill_find → skill_load → skill_read_file es divulgación progresiva reconstruida como un pull, hasta el final: el costo siempre cargado deja de escalar con el tamaño del catálogo, y los documentos/scripts de referencia incluidos en una skill permanecen fuera del contexto hasta que se nombran por ruta, incluso después de que la skill misma se haya cargado.

tool_find y tool_call solo aparecen una vez que has configurado servidores MCP upstream mediante skilljit adopt (ver abajo) — ejecuta solo-skills y la superficie es de 4 herramientas, no 6. Esto es lo que hace que la mitad de skills sea independientemente distribuible y testeable desde la mitad de proxy.

Múltiples pestañas / sesiones paralelas

Ejecutar varias pestañas de Claude Code a la vez para diferentes tareas es exactamente donde el costo de "cada pestaña paga por cada skill instalada" se multiplica: con N pestañas abiertas, esa sobrecarga por turno se paga N veces simultáneamente. skilljit ya reduce ese costo por pestaña a unas pocas herramientas fijas independientemente del tamaño del catálogo, pero skilljit_stats() va más allá: los números de línea base/actuales de cada sesión también se escriben en el catalog.db compartido (el mismo archivo al que ya apunta el proceso skilljit serve de cada pestaña), así que los totales reportados son acumulativos en cada pestaña que hayas tenido abierta, no solo la que estás consultando. Perder una pestaña no pierde ese número: ya estaba escrito de forma duradera, no solo en la memoria de esa pestaña.

Esto no recupera la conversación en sí de una pestaña perdida — eso es una función de sesión de Claude Code (claude --resume / --continue), no relacionada con skilljit. Lo que arregla específicamente es el punto ciego de la contabilidad de tokens: "cuánto me ha ahorrado realmente skilljit hoy, en todo lo que tenía abierto", sobreviviendo a la muerte de cualquier pestaña.

Proxy MCP — enrutando tus otros servidores MCP

Pasar skilljit serve --config <path> (la ruta de configuración sobre la que ejecutaste skilljit adopt) activa tool_find/tool_call para los servidores que adoptó. La seguridad es lo primero aquí, ya que toca configuraciones de las que ya dependes:

• skilljit init <configPath> nunca muta el archivo original: escribe una configuración propuesta e imprime un diff.

• skilljit adopt <configPath> es una ejecución en seco por defecto; pasa --yes para escribir realmente el cambio, después de hacer una copia de seguridad del original.

• --keep server1,server2 deja esos servidores intactos — completamente visibles en la lista estática de herramientas, sin round-trip de tool_find. Útil para herramientas de ruta caliente que llamas en cada turno. (Keep es por servidor, no por herramienta, en esta versión.)

• skilljit doctor [configPath] verifica que cada upstream adoptado aún se lance, haga handshake y liste herramientas.

• skilljit restore <configPath> es un comando que restaura la configuración original.

• Que un servidor MCP upstream no esté disponible no afecta a los demás: tool_call devuelve un error limpio para ese servidor, todo lo demás sigue funcionando.

Seguridad

Las skills son, funcionalmente, instrucciones de un desconocido que un agente seguirá: Anthropic advierte explícitamente que una skill maliciosa puede exfiltrar datos o hacer mal uso de las herramientas. skilljit trata eso como una característica para la que diseñar, no como una ocurrencia tardía:

• Cada resultado de skill_find muestra el estado de auditoría de la skill junto a su descripción.

• skill_load advierte en voz alta en el contenido devuelto cuando una skill falló su auditoría, o no ha sido auditada en absoluto — la misma postura que instalar software de una fuente desconocida.

Benchmark

bench/ incluye un conjunto etiquetado de 41 pares (tarea → skill correcta) y un harness de recall@k, para que "la búsqueda funciona" sea una afirmación medida en lugar de una vibra. Números actuales, reproducibles con 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%)

La búsqueda es SQLite FTS5 + BM25 — sin embeddings en v1. Esa es una decisión deliberada de YAGNI: FTS5 se envía idénticamente tanto en la implementación de Node (better-sqlite3) como en la de Python (stdlib), sin descarga de modelos ni dependencias de runtime adicionales. El riesgo residual de recall (las descripciones de skills son semánticas — "usa cuando el usuario mencione PDFs…") se mitiga estructuralmente: skill_find devuelve varios candidatos para que Claude los considere y vuelva a consultar, en lugar de comprometerse con un resultado top-1 de un solo disparo. Los embeddings siguen siendo una opción opt-in, para añadirse solo si este benchmark muestra que el recall de FTS5 es genuinamente inadecuado — los tres fallos de arriba (todos casi-aciertos, la skill correcta justo fuera del top 3) son los candidatos concretos para esa decisión.

Publicación

Empujar una etiqueta v* (por ejemplo, v0.1.2) ejecuta CI y luego publica cada paquete en npm y PyPI mediante Trusted Publishing (OIDC) — sin secretos de larga duración NPM_TOKEN/PYPI_TOKEN en este repo. Ver .github/workflows/release.yml.

Se requiere una configuración única antes de que eso funcione, hecha manualmente (no se puede automatizar):

• En npmjs.com, registra un Trusted Publisher para cada uno de @skilljit/core, @skilljit/proxy, @skilljit/mcp y skilljit, apuntando a este repo, al archivo de workflow release.yml y al entorno npm.

• En pypi.org, registra un Trusted Publisher para el proyecto skilljit, apuntando a este repo, al archivo de workflow release.yml y al entorno pypi.

Arquitectura

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 es la única implementación; el paquete PyPI es un envoltorio fino y honesto alrededor de él, no una segunda implementación de la lógica de ranking.

Licencia

MIT