skilljit 0.1.0

package/README.md

@@ -0,0 +1,186 @@
+# skilljit
+
+Just-in-time skill and MCP tool routing for Claude — install thousands of skills at
+the token cost of one. Nothing loads into context until a task actually needs it.
+
+## Why the tool list never changes
+
+The obvious way to add tools on demand is the MCP `notifications/tools/list_changed`
+notification. It's broken in Claude Desktop —
+[anthropics/claude-code#50339](https://github.com/anthropics/claude-code/issues/50339)
+documents it being ignored across 336+ versions (empty client capabilities, an SDK
+handler that never fires, a frozen tool-list reference) and Anthropic closed the issue
+as **not planned**. The issue's own recommended workaround is to *"declare all tools
+at startup and dispatch internally via mode/action parameters."*
+
+That's what skilljit does. Its MCP tool list is **fixed and never changes** — five
+tools, always. Skills and upstream MCP tools are found and loaded through those five
+tools, not by re-registering the tool list. This is why skilljit works on Claude
+Desktop, Claude Code, Codex, and Cursor while `list_changed`-based proxies silently
+degrade on at least one of them.
+
+## The problem
+
+Claude's Agent Skills use progressive disclosure: each skill's `name` + `description`
+(~100 tokens) sits in the system prompt on every turn, and only the body loads on
+demand. That works at 10 skills. It collapses at scale — the ecosystem is already
+there, with tens of thousands of skills across thousands of repos. Installing 200 of
+them costs tens of thousands of tokens *per turn*, forever. So nobody does — everyone
+installs ten and the rest are unreachable.
+
+MCP has the identical problem, worse: every connected server's full tool schemas load
+at startup, commonly 20–50k tokens before the user types anything.
+
+| | Without skilljit | With skilljit |
+|---|---|---|
+| Skills reachable | ~10 | tens of thousands |
+| Per-turn skill overhead | 1k–20k tokens, grows forever | ~flat |
+| Per-turn MCP tool overhead | 20k–50k tokens | ~flat |
+
+## Install
+
+```bash
+npx -y skilljit sync
+```
+
+That's the primary path — the MCP ecosystem is npx-first, and Claude Code / Desktop
+configs already expect this shape.
+
+A thin Python companion is also published for
+[`claude-agent-sdk`](https://pypi.org/project/skilljit/) users who want to query the
+same catalog directly instead of going through MCP:
+
+```bash
+pip install skilljit
+```
+
+See [`python/README.md`](https://github.com/aqibsidd/skilljit/blob/main/python/README.md)
+for what that package does and doesn't do — it forwards the CLI to `npx -y skilljit`
+and adds a read-only `Catalog` for Python.
+
+## Quickstart
+
+```bash
+# 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
+```
+
+Add to your MCP client config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "skilljit": {
+      "command": "npx",
+      "args": ["-y", "skilljit", "serve"]
+    }
+  }
+}
+```
+
+Other commands: `skilljit stats` (catalog size + how to read live savings),
+`skilljit init <configPath>` (preview routing your existing MCP servers through
+skilljit — never mutates the original), `skilljit adopt <configPath>` (apply it),
+`skilljit doctor [configPath]` (verify upstreams still work), `skilljit restore
+<configPath>` (undo `adopt`).
+
+## The five tools
+
+skilljit exposes a fixed surface — it never grows or shrinks at runtime.
+
+| Tool | Returns |
+|---|---|
+| `skill_find(query, limit=8)` | Cheap candidates: id, source, one-line description, install count, audit status. |
+| `skill_load(name)` | Full SKILL.md body for one skill by id. The only point a skill's full content enters context. |
+| `tool_find(query, limit=8)` | Matching upstream MCP tools' full JSON Schema, across every connected server. |
+| `tool_call(server, tool, args)` | Generic dispatcher to the matched upstream server and tool. |
+| `skilljit_stats()` | Tokens saved this session vs. loading every cataloged skill (and configured tool) the traditional way. |
+
+`skill_find` → `skill_load` is progressive disclosure rebuilt as a **pull**: the
+always-loaded cost stops scaling with catalog size.
+
+`tool_find` and `tool_call` only appear once you've configured upstream MCP servers
+via `skilljit adopt` (see below) — run skills-only and the surface is 3 tools, not 5.
+This is what makes the skills half independently shippable and testable from the
+proxy half.
+
+## MCP proxy — routing your other MCP servers
+
+Passing `skilljit serve --config <path>` (the config path you previously ran
+`skilljit adopt` on) turns on `tool_find`/`tool_call` for the servers it adopted.
+Safety comes first here, since this touches configs you already rely on:
+
+- **`skilljit init <configPath>`** never mutates the original file — it writes a
+  proposed config and prints a diff.
+- **`skilljit adopt <configPath>`** is a dry run by default; pass `--yes` to actually
+  write the change, after backing up the original.
+- **`--keep server1,server2`** leaves those servers untouched — fully visible in the
+  static tool list, no `tool_find` round-trip. Useful for hot-path tools you call on
+  every turn. (Keep is per-server, not per-tool, in this version.)
+- **`skilljit doctor [configPath]`** verifies every adopted upstream still spawns,
+  handshakes, and lists tools.
+- **`skilljit restore <configPath>`** is one command that puts the original config
+  back.
+- One upstream MCP server being unavailable doesn't affect the others: `tool_call`
+  returns a clean error for that server, everything else keeps working.
+
+## Security
+
+Skills are, functionally, instructions from a stranger that an agent will follow —
+Anthropic warns explicitly that a malicious skill can exfiltrate data or misuse tools.
+skilljit treats that as a feature to design for, not an afterthought:
+
+- Every `skill_find` result surfaces the skill's audit status alongside its
+  description.
+- `skill_load` warns loudly in the returned content when a skill failed its audit, or
+  hasn't been audited at all — the same posture as installing software from an
+  unknown source.
+
+## Benchmark
+
+The repo ships a labeled set of 41 `(task → correct skill)` pairs and a recall@k
+harness, so "the search works" is a measured claim rather than a vibe. Current
+numbers, reproducible with
+[`node bench/run.mjs`](https://github.com/aqibsidd/skilljit/blob/main/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%)
+```
+
+Search is SQLite FTS5 + BM25 — no embeddings in v1. That's a deliberate YAGNI call:
+FTS5 ships identically in both the Node (`better-sqlite3`) and Python (stdlib)
+implementations, with no model download or extra runtime deps. The residual recall
+risk (skill descriptions are semantic — "use when the user mentions PDFs…") is
+mitigated structurally: `skill_find` returns several candidates for Claude to
+consider and re-query on, rather than committing to a one-shot top-1 result.
+Embeddings stay an opt-in option, to be added only if this benchmark shows FTS5
+recall is genuinely inadequate.
+
+## Architecture
+
+```
+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 five fixed tools)
+  packages/cli/      skilljit sync | search | serve | stats | init | adopt | restore | doctor  (this package)
+  python/            pip package — CLI shim + read-only query API for Agent SDK users
+  bench/             labeled task→skill eval set + recall@k harness
+```
+
+See the [main repo](https://github.com/aqibsidd/skilljit) for the full source,
+issue tracker, and publishing setup.
+
+## License
+
+MIT

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { Catalog, defaultCatalogPath } from "@skilljit/core";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "@skilljit/mcp";
+import { latestAdoption, resolveManagedUpstreams } from "@skilljit/proxy";
+import { runSync } from "./commands/sync.js";
+import { runSearch, formatSearchResults } from "./commands/search.js";
+import { defaultStateDir, cmdInit, cmdAdopt, cmdRestore, cmdDoctor } from "./commands/proxy.js";
+const program = new Command();
+program
+    .name("skilljit")
+    .description("Just-in-time skill and MCP tool routing for Claude. " +
+    "Install thousands of skills at the token cost of one — nothing loads " +
+    "into context until a task actually needs it.")
+    .version("0.1.0");
+program
+    .command("sync")
+    .description("Refresh the local skill catalog from configured GitHub sources")
+    .option("--db <path>", "catalog db path", defaultCatalogPath())
+    .action(async (options) => {
+    const result = await runSync({ dbPath: options.db, log: (l) => console.log(l) });
+    console.log(`\nDone. ${result.total} skill(s) in catalog.`);
+    if (result.failedSources.length > 0) {
+        console.log(`${result.failedSources.length} source(s) failed to sync (see above).`);
+    }
+});
+program
+    .command("search <query>")
+    .description("Search the local skill catalog (no network, no context cost)")
+    .option("--db <path>", "catalog db path", defaultCatalogPath())
+    .option("-n, --limit <n>", "max results", "8")
+    .action((query, options) => {
+    const hits = runSearch({ dbPath: options.db, query, limit: Number(options.limit) });
+    console.log(formatSearchResults(hits));
+});
+program
+    .command("serve")
+    .description("Run the skilljit MCP stdio server (this is what your MCP client config should launch)")
+    .option("--db <path>", "catalog db path", defaultCatalogPath())
+    .option("--config <path>", "MCP client config previously passed to `skilljit adopt`, to enable tool_find/tool_call")
+    .action(async (options) => {
+    let upstreams;
+    if (options.config) {
+        const record = latestAdoption(defaultStateDir(), options.config);
+        if (record)
+            upstreams = resolveManagedUpstreams(record);
+    }
+    const { server } = createServer({ catalogPath: options.db, upstreams });
+    await server.connect(new StdioServerTransport());
+});
+program
+    .command("stats")
+    .description("Print current catalog size (token savings accrue per-session inside a running MCP connection)")
+    .option("--db <path>", "catalog db path", defaultCatalogPath())
+    .action((options) => {
+    const catalog = new Catalog(options.db);
+    console.log(`${catalog.count()} skill(s) in local catalog (${options.db}).`);
+    console.log("Run `skilljit serve` and call the skilljit_stats tool from your MCP client for live savings.");
+    catalog.close();
+});
+function parseKeepList(value) {
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+program
+    .command("init <configPath>")
+    .description("Preview adopting an MCP client config (e.g. claude_desktop_config.json) into skilljit — never touches the original file")
+    .option("--keep <names>", "comma-separated server names to leave untouched (fully visible, no routing)", parseKeepList, [])
+    .action(async (configPath, options) => {
+    await cmdInit({ configPath, keep: options.keep }, (l) => console.log(l));
+});
+program
+    .command("adopt <configPath>")
+    .description("Route servers in an MCP client config through skilljit (backs up the original first)")
+    .option("--keep <names>", "comma-separated server names to leave untouched", parseKeepList, [])
+    .option("--yes", "actually write the change (otherwise this is a dry run)")
+    .action(async (configPath, options) => {
+    await cmdAdopt({ configPath, keep: options.keep, yes: options.yes }, (l) => console.log(l));
+});
+program
+    .command("restore <configPath>")
+    .description("Undo `skilljit adopt` — restores the config from its backup")
+    .action(async (configPath) => {
+    await cmdRestore(configPath, undefined, (l) => console.log(l));
+});
+program
+    .command("doctor [configPath]")
+    .description("Check that every upstream MCP server skilljit is routing for a config still spawns and lists tools")
+    .action(async (configPath) => {
+    if (!configPath) {
+        console.log("Usage: skilljit doctor <configPath> (the config previously passed to `skilljit adopt`)");
+        return;
+    }
+    await cmdDoctor(configPath, undefined, (l) => console.log(l));
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":"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"}

package/dist/commands/proxy.d.ts

@@ -0,0 +1,12 @@
+export declare function defaultStateDir(): string;
+export interface ProxyCliOptions {
+    configPath: string;
+    keep: string[];
+    stateDir?: string;
+}
+export declare function cmdInit(opts: ProxyCliOptions, log: (s: string) => void): Promise<void>;
+export declare function cmdAdopt(opts: ProxyCliOptions & {
+    yes?: boolean;
+}, log: (s: string) => void): Promise<void>;
+export declare function cmdRestore(configPath: string, stateDir: string | undefined, log: (s: string) => void): Promise<void>;
+export declare function cmdDoctor(configPath: string, stateDir: string | undefined, log: (s: string) => void): Promise<void>;

package/dist/commands/proxy.js

@@ -0,0 +1,54 @@
+import os from "node:os";
+import path from "node:path";
+import { runInit, runAdopt, runRestore, runDoctor, resolveManagedUpstreams, latestAdoption, } from "@skilljit/proxy";
+export function defaultStateDir() {
+    return process.env.SKILLJIT_HOME ?? path.join(os.homedir(), ".skilljit");
+}
+export async function cmdInit(opts, log) {
+    const result = await runInit({
+        configPath: opts.configPath,
+        stateDir: opts.stateDir ?? defaultStateDir(),
+        passthroughServerNames: opts.keep,
+    });
+    log(`Proposed config written to ${result.proposedPath} (original untouched).\n`);
+    log("Changes:");
+    log(result.diff);
+    log(`\n${result.routedServerNames.length} server(s) would be routed through skilljit: ${result.routedServerNames.join(", ") || "(none)"}`);
+    log(`\nReview it, then run: skilljit adopt ${opts.configPath} --yes` + (opts.keep.length ? ` --keep ${opts.keep.join(",")}` : ""));
+}
+export async function cmdAdopt(opts, log) {
+    if (!opts.yes) {
+        log("This will rewrite your MCP config in place (a backup is kept for `skilljit restore`).");
+        log("Re-run with --yes to proceed, or `skilljit init` first to preview the diff.");
+        return;
+    }
+    const record = await runAdopt({
+        configPath: opts.configPath,
+        stateDir: opts.stateDir ?? defaultStateDir(),
+        passthroughServerNames: opts.keep,
+    });
+    log(`Adopted. Backup saved to ${record.backupPath}.`);
+    log(`Routed servers: ${record.routedServerNames.join(", ") || "(none)"}`);
+    log(`Restart your MCP client, then run \`skilljit restore ${opts.configPath}\` any time to undo this.`);
+}
+export async function cmdRestore(configPath, stateDir, log) {
+    await runRestore({ configPath, stateDir: stateDir ?? defaultStateDir() });
+    log(`Restored ${configPath} to its pre-adopt state.`);
+}
+export async function cmdDoctor(configPath, stateDir, log) {
+    const record = latestAdoption(stateDir ?? defaultStateDir(), configPath);
+    if (!record) {
+        log(`No skilljit adoption found for ${configPath}. Nothing to check — run \`skilljit init\` / \`adopt\` first.`);
+        return;
+    }
+    const specs = resolveManagedUpstreams(record);
+    if (specs.length === 0) {
+        log("No routed upstream servers to check.");
+        return;
+    }
+    const report = await runDoctor(specs);
+    for (const [name, entry] of Object.entries(report)) {
+        log(entry.ok ? `✓ ${name} — ${entry.toolCount} tool(s)` : `✗ ${name} — ${entry.error}`);
+    }
+}
+//# sourceMappingURL=proxy.js.map

package/dist/commands/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../../src/commands/proxy.ts"],"names":[],"mappings":"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"}

package/dist/commands/search.d.ts

@@ -0,0 +1,8 @@
+import type { SkillSearchHit } from "@skilljit/core";
+export interface SearchOptions {
+    dbPath: string;
+    query: string;
+    limit?: number;
+}
+export declare function runSearch(opts: SearchOptions): SkillSearchHit[];
+export declare function formatSearchResults(hits: SkillSearchHit[]): string;

package/dist/commands/search.js

@@ -0,0 +1,21 @@
+import { Catalog } from "@skilljit/core";
+export function runSearch(opts) {
+    const catalog = new Catalog(opts.dbPath);
+    try {
+        return catalog.searchSkills(opts.query, opts.limit ?? 8);
+    }
+    finally {
+        catalog.close();
+    }
+}
+export function formatSearchResults(hits) {
+    if (hits.length === 0)
+        return "No matching skills found.";
+    return hits
+        .map((h, i) => {
+        const audit = h.skill.auditStatus && h.skill.auditStatus !== "unaudited" ? ` [audit: ${h.skill.auditStatus}]` : "";
+        return `${i + 1}. ${h.skill.name} (${h.skill.source})${audit}\n   ${h.skill.description}`;
+    })
+        .join("\n");
+}
+//# sourceMappingURL=search.js.map

package/dist/commands/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/commands/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AASzC,MAAM,UAAU,SAAS,CAAC,IAAmB;IAC3C,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC;IAC3D,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAsB;IACxD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,2BAA2B,CAAC;IAC1D,OAAO,IAAI;SACR,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACZ,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,WAAW,IAAI,CAAC,CAAC,KAAK,CAAC,WAAW,KAAK,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACnH,OAAO,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,QAAQ,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;IAC5F,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}

package/dist/commands/sync.d.ts

@@ -0,0 +1,28 @@
+export interface SyncOptions {
+    dbPath: string;
+    sources?: {
+        owner: string;
+        repo: string;
+    }[];
+    fetchImpl?: typeof fetch;
+    log?: (line: string) => void;
+}
+export interface SyncResult {
+    total: number;
+    perSource: {
+        owner: string;
+        repo: string;
+        count: number;
+    }[];
+    failedSources: {
+        owner: string;
+        repo: string;
+    }[];
+}
+/**
+ * Ingest every configured GitHub source into the local catalog db.
+ * One source failing (network error, rate limit, repo renamed) does not
+ * abort the rest — skilljit's catalog should degrade gracefully, not
+ * die because one upstream repo is briefly unavailable.
+ */
+export declare function runSync(opts: SyncOptions): Promise<SyncResult>;

package/dist/commands/sync.js

@@ -0,0 +1,34 @@
+import { Catalog, ingestGithubRepo, DEFAULT_GITHUB_SOURCES } from "@skilljit/core";
+/**
+ * Ingest every configured GitHub source into the local catalog db.
+ * One source failing (network error, rate limit, repo renamed) does not
+ * abort the rest — skilljit's catalog should degrade gracefully, not
+ * die because one upstream repo is briefly unavailable.
+ */
+export async function runSync(opts) {
+    const log = opts.log ?? (() => { });
+    const sources = opts.sources ?? DEFAULT_GITHUB_SOURCES;
+    const catalog = new Catalog(opts.dbPath);
+    const perSource = [];
+    const failedSources = [];
+    try {
+        for (const { owner, repo } of sources) {
+            log(`syncing github:${owner}/${repo} ...`);
+            try {
+                const skills = await ingestGithubRepo(owner, repo, { fetchImpl: opts.fetchImpl });
+                catalog.upsertSkills(skills);
+                perSource.push({ owner, repo, count: skills.length });
+                log(`  ${skills.length} skill(s) found`);
+            }
+            catch (err) {
+                failedSources.push({ owner, repo });
+                log(`  failed: ${err.message}`);
+            }
+        }
+        return { total: catalog.count(), perSource, failedSources };
+    }
+    finally {
+        catalog.close();
+    }
+}
+//# sourceMappingURL=sync.js.map

package/dist/commands/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAenF;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAiB;IAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,sBAAsB,CAAC;IACvD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,SAAS,GAA4B,EAAE,CAAC;IAC9C,MAAM,aAAa,GAAgC,EAAE,CAAC;IAEtD,IAAI,CAAC;QACH,KAAK,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,OAAO,EAAE,CAAC;YACtC,GAAG,CAAC,kBAAkB,KAAK,IAAI,IAAI,MAAM,CAAC,CAAC;YAC3C,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;gBAClF,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;gBAC7B,SAAS,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;gBACtD,GAAG,CAAC,KAAK,MAAM,CAAC,MAAM,iBAAiB,CAAC,CAAC;YAC3C,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,aAAa,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBACpC,GAAG,CAAC,aAAc,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;YAC7C,CAAC;QACH,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC;IAC9D,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { runSync } from "./commands/sync.js";
+export type { SyncOptions, SyncResult } from "./commands/sync.js";
+export { runSearch, formatSearchResults } from "./commands/search.js";
+export type { SearchOptions } from "./commands/search.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { runSync } from "./commands/sync.js";
+export { runSearch, formatSearchResults } from "./commands/search.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "skilljit",
+  "version": "0.1.0",
+  "description": "Just-in-time skill and MCP tool routing for Claude — install thousands of skills at the token cost of one.",
+  "type": "module",
+  "license": "MIT",
+  "author": "aqibsidd",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aqibsidd/skilljit.git"
+  },
+  "homepage": "https://github.com/aqibsidd/skilljit#readme",
+  "bugs": "https://github.com/aqibsidd/skilljit/issues",
+  "bin": {
+    "skilljit": "./dist/bin.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "claude",
+    "mcp",
+    "agent-skills",
+    "claude-code",
+    "token-optimization"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/bin.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@skilljit/core": "^0.1.0",
+    "@skilljit/mcp": "^0.1.0",
+    "@skilljit/proxy": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "commander": "^15.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.11"
+  }
+}