skilljit

Claude를 위한 적시(Just-in-time) 스킬 및 MCP 도구 라우팅 — 수천 개의 스킬을 토큰 하나의 비용으로 설치하세요. 작업이 실제로 필요해지기 전까지는 아무것도 컨텍스트에 로드되지 않습니다.

도구 목록이 절대 변하지 않는 이유

요청 시 도구를 추가하는 가장 확실한 방법은 MCP notifications/tools/list_changed 알림입니다. 하지만 Claude Desktop에서는 이 기능이 고장나 있습니다 — anthropics/claude-code#50339 에 336개 이상의 버전에서 무시되고 있음(빈 클라이언트 capabilities, 절대 실행되지 않는 SDK 핸들러, 동결된 도구 목록 참조)이 문서화되어 있으며, Anthropic은 이 이슈를 not planned으로 종료했습니다. 이 이슈에서 권장하는 해결책은 *"시작 시 모든 도구를 선언하고 mode/action 파라미터를 통해 내부적으로 디스패치하라"*는 것입니다.

그것이 바로 skilljit이 하는 일입니다. skilljit의 MCP 도구 목록은 고정되어 있으며 절대 변하지 않습니다 — 항상 작고 일정한 수의 도구만 유지합니다. 스킬과 상위 MCP 도구는 도구 목록을 다시 등록하는 방식이 아니라 이러한 도구들을 통해 발견되고 로드됩니다. 이것이 skilljit이 Claude Desktop, Claude Code, Codex, Cursor에서 모두 작동하는 반면, list_changed 기반 프록시는 그중 적어도 하나에서 조용히 성능이 저하되는 이유입니다.

Related MCP server: context-saver

문제

Claude의 Agent Skills는 점진적 공개(progressive disclosure)를 사용합니다: 각 스킬의 name + description(~100 토큰)이 매 턴마다 시스템 프롬프트에 포함되고, 본문만 요청 시 로드됩니다. 이는 10개의 스킬에서는 잘 작동합니다. 하지만 규모가 커지면 무너집니다 — 생태계는 이미 수천 개의 저장소에 걸쳐 수만 개의 스킬이 존재하는 상태입니다. 200개를 설치하면 매 턴마다 수만 개의 토큰이 영구적으로 소모됩니다. 그래서 아무도 그렇게 하지 않습니다 — 모두 10개만 설치하고 나머지는 접근할 수 없게 됩니다.

MCP도 동일한 문제를 가지고 있으며, 더 심각합니다: 연결된 모든 서버의 전체 도구 스키마가 시작 시 로드되어, 사용자가 아무것도 입력하기 전에 일반적으로 20–50k 토큰이 소모됩니다.

설치

npx -y skilljit sync

이것이 기본 경로입니다 — MCP 생태계는 npx 우선이며, Claude Code / Desktop 구성은 이미 이 형태를 기대합니다.

또한 MCP를 거치지 않고 동일한 카탈로그를 직접 쿼리하려는 claude-agent-sdk 사용자를 위해 얇은 Python 동반 패키지도 게시되어 있습니다:

pip install skilljit

이 패키지가 무엇을 하고 무엇을 하지 않는지에 대해서는 python/README.md를 참조하세요 — CLI를 npx -y skilljit으로 전달하고 Python용 읽기 전용 Catalog를 추가합니다.

Node 버전 지원

skilljit, @skilljit/mcp, @skilljit/proxy는 **Node 18+**가 필요합니다 — 이 최소 버전은 MCP 서버와 프록시 계층이 의존하는 @modelcontextprotocol/sdk에서 직접 비롯되며, SDK 자체가 18+를 요구합니다. MCP 지원을 포기하지 않는 한 이 제약을 피할 방법은 없습니다.

@skilljit/core(카탈로그/검색 라이브러리, MCP 의존성 없음)는 Catalog/ingestGithubRepo API를 직접 사용하는 모든 사람을 위해 **Node 16+**를 지원합니다. 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 소스는 GitHub API 대신 베어 미러 클론과 git worktree를 통해 수집됩니다: 첫 번째 sync는 전체 클론 비용을 지불하고, 이후의 모든 sync는 저렴한 git fetch + worktree 체크아웃입니다 — 속도 제한 없음, 토큰 없음, git 자체가 도달할 수 있는 모든 것에 대해 작동합니다.

여섯 가지 도구

skilljit은 고정된 표면을 노출합니다 — 런타임에 늘어나거나 줄어들지 않습니다.

skill_find → skill_load → skill_read_file은 점진적 공개를 풀(pull) 방식으로 재구축한 것입니다: 항상 로드되는 비용은 카탈로그 크기에 따라 더 이상 증가하지 않으며, 스킬의 번들된 참조 문서/스크립트는 스킬 자체가 로드된 후에도 경로로 지정되기 전까지 컨텍스트에 들어오지 않습니다.

tool_find와 tool_call은 skilljit adopt(아래 참조)를 통해 상위 MCP 서버를 구성한 후에만 나타납니다 — 스킬 전용으로 실행하면 표면은 6개가 아닌 4개의 도구입니다. 이것이 스킬 부분을 프록시 부분과 독립적으로 배포하고 테스트할 수 있게 만드는 이유입니다.

여러 탭 / 병렬 세션

서로 다른 작업을 위해 여러 Claude Code 탭을 동시에 실행하는 것은 "모든 탭이 설치된 모든 스킬에 대한 비용을 지불한다"는 비용이 배가되는 바로 그 상황입니다 — N개의 탭이 열려 있으면 턴당 오버헤드가 동시에 N번 지불됩니다. skilljit은 이미 카탈로그 크기와 관계없이 탭당 비용을 고정된 몇 개의 도구로 줄이지만, skilljit_stats()는 더 나아갑니다: 모든 세션의 기준/실제 수치가 공유 catalog.db(모든 탭의 skilljit serve 프로세스가 이미 가리키는 동일한 파일)에도 기록되므로, 보고된 합계는 지금까지 열었던 모든 탭에 걸쳐 누적됩니다. 탭을 잃어도 그 숫자는 사라지지 않습니다 — 이미 영구적으로 기록되었으며, 해당 탭의 메모리에만 보관된 것이 아닙니다.

이것은 잃어버린 탭의 대화 자체를 복구하지는 않습니다 — 그것은 Claude Code 세션 기능(claude --resume / --continue)이며 skilljit과는 무관합니다. 이 기능이 구체적으로 해결하는 것은 토큰 회계의 사각지대입니다: "오늘 skilljit이 열어둔 모든 것을 통틀어 실제로 얼마나 절약했는가" — 어떤 탭이 죽어도 유지됩니다.

MCP 프록시 — 다른 MCP 서버 라우팅

skilljit serve --config <path>(이전에 skilljit adopt를 실행한 구성 경로)를 전달하면 채택한 서버에 대해 tool_find/tool_call이 활성화됩니다. 이미 의존하고 있는 구성을 건드리기 때문에 안전이 최우선입니다:

• skilljit init <configPath> 원본 파일을 절대 변경하지 않습니다 — 제안된 구성을 작성하고 diff를 출력합니다.

• 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(표준 라이브러리) 구현 모두에서 동일하게 제공되며, 모델 다운로드나 추가 런타임 의존성이 없습니다. 잔여 recall 위험(스킬 설명은 의미론적입니다 — "사용자가 PDF를 언급할 때 사용…")은 구조적으로 완화됩니다: skill_find는 일회성 top-1 결과에 집중하는 대신 Claude가 고려하고 다시 쿼리할 수 있는 여러 후보를 반환합니다. 임베딩은 선택적 옵션으로 남아 있으며, 이 벤치마크가 FTS5 recall이 실제로 부적절하다는 것을 보여줄 때만 추가됩니다 — 위의 세 가지 누락(모두 근접 실패, 올바른 스킬이 top 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 각각에 대해 이 저장소, release.yml 워크플로 파일, npm 환경을 가리키는 Trusted Publisher를 등록하세요.

• pypi.org에서 skilljit 프로젝트에 대해 이 저장소, release.yml 워크플로 파일, pypi 환경을 가리키는 Trusted Publisher를 등록하세요.

아키텍처

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