Skillfish Router

Silent, minimal-context skill router for Claude Code and Claude Desktop. Every prompt is intercepted and the Skill Router determines the Skills Needed — the minimum set of installed skills required for the request — which is surfaced to the model invisibly, unless you ask "how were skills determined?".

Skills Needed from Skill Router. The Skill Router is the only component that decides which skills a request needs. Everything downstream (the hook injection, the MCP tools, the model) consumes the router's Skills Needed — nothing re-selects or re-ranks skills independently. This keeps context minimal (1–3 skills, names only) while staying correct.

Cross-platform (macOS · Windows · Linux). One runtime dependency (@modelcontextprotocol/sdk); the routing core has none.

• How it decides / internals: ARCHITECTURE.md
• Why hook + MCP (and not MCP alone): a pure MCP server can't intercept prompts — only a UserPromptSubmit hook runs per-prompt. This ships both.

One-command install

npx (all platforms — recommended):

npx @akbuilds/skillfish-router install

That's it — no clone, no global install. You can also install globally:

npm install -g @akbuilds/skillfish-router && skillfish-router install

Or, from a downloaded release: double-click install.command (macOS) or install.bat (Windows); on Linux run bash installers/install.sh.

The install command:

1. Detects Claude Code and Claude Desktop.
2. Backs up your Claude config (atomic writes; rollback on failure).
3. Copies the dependency-free hook/daemon runtime to a stable ~/.skillfish/runtime and installs the UserPromptSubmit hook pointing there (so it survives npx cache eviction and upgrades).
4. Registers the MCP server as npx -y @akbuilds/skillfish-router@<ver> mcp for Claude Code and (if present) Claude Desktop — the modern MCP convention.
5. Indexes your installed Skillfish skills.
6. Runs a final health check (doctor).

Idempotent — run it again anytime; it converges to exactly one hook and one MCP entry. Verify with:

npx @akbuilds/skillfish-router doctor

CLI

Run any command with npx @akbuilds/skillfish-router <command> (or the bare skillfish-router <command> after a global install):

  install          Install the hook + register the MCP server
  uninstall        Remove everything it added, restoring prior config
  update           Upgrade the package, then re-apply configuration
  doctor           Diagnose runtime, build, live server, and wiring
  status           Concise snapshot of the current install
  rebuild-index    Force-rebuild the capability index
  mcp              Run the MCP server over stdio (Claude launches this via npx)
  version          Print the version

Global:   --dry-run  --json  --yes/-y  --help/-h  --version/-V
install:  --no-hook  --no-mcp  --no-desktop  --code-only  --desktop-only  --force-desktop
uninstall:--restore-backup  --purge
update:   --local

--dry-run prints every change without writing a byte — safe to try first. mcp is invoked by Claude, not by you.

Uninstall

npx @akbuilds/skillfish-router uninstall                 # surgical: removes only what it added
npx @akbuilds/skillfish-router uninstall --restore-backup # byte-for-byte restore from backup
npx @akbuilds/skillfish-router uninstall --purge          # also delete ~/.skillfish (runtime + backups)

The surgical default preserves any unrelated hooks or MCP servers you have. Backups live in ~/.skillfish/backups/ (or %USERPROFILE%\.skillfish\backups\).

What it does to your config

| Target | File | Change | | --- | --- | --- | | Claude Code (hook) | ~/.claude/settings.json | one UserPromptSubmit hook → node "~/.skillfish/runtime/…/user-prompt-submit.js" | | Claude Code (MCP) | ~/.claude.json | mcpServers["skillfish-router"] = npx -y @akbuilds/skillfish-router@<ver> mcp | | Claude Desktop (MCP) | platform config¹ | mcpServers["skillfish-router"] = npx -y @akbuilds/skillfish-router@<ver> mcp |

¹ macOS ~/Library/Application Support/Claude/claude_desktop_config.json · Windows %APPDATA%\Claude\claude_desktop_config.json · Linux ~/.config/Claude/claude_desktop_config.json.

All writes are atomic (temp + rename) and preceded by a full backup. Nothing is hardcoded — every path derives from os.homedir() and platform conventions, and all are overridable via env vars (used by CI to sandbox the whole flow).

Troubleshooting

skillfish-router: command not found after install. The npm global bin dir isn't on your PATH. Find it with npm bin -g (or npm prefix -g) and add it to PATH. On Windows, open a new terminal so PATH refreshes.

doctor says "node on PATH" is a warning. Claude spawns the hook/MCP via node. If your shell can't find node non-interactively, install Node system-wide or ensure your shell profile exports it. The router still works when launched from a shell that has node.

doctor says "MCP server starts: probe failed". The build is missing or corrupt. Re-run npx @akbuilds/skillfish-router install (or … update), then … doctor again.

Claude Code doesn't seem to route. Hooks load at session start — fully restart Claude Code after installing. Confirm wiring with skillfish-router status (hook=yes, mcp=yes).

Claude Desktop doesn't show the server. Restart Claude Desktop after install — it reads its config on launch.

"Claude Desktop not detected — skipping." Its app-data folder doesn't exist yet. Install/launch Claude Desktop once, then re-run skillfish-router install, or force it with --force-desktop.

A config file failed to parse. The installer refuses to overwrite a config it can't parse (to avoid data loss). Fix the JSON syntax in the reported file, then re-run.

Undo everything, exactly. skillfish-router uninstall --restore-backup restores each touched file from the install-time backup (or deletes files the installer created).

PowerShell blocks the script. Use the provided install.bat, or run powershell -ExecutionPolicy Bypass -File installers\install.ps1.

Enterprise / non-standard config location. Set CLAUDE_CONFIG_DIR, SKILLFISH_CODE_SETTINGS, SKILLFISH_CODE_MCP_CONFIG, SKILLFISH_DESKTOP_CONFIG, or SKILLFISH_HOME to point at custom paths.

Development

git clone … && cd skillfish-router
npm install
npm run build        # emit dist/
npm test             # unit tests
npm run smoke        # cross-platform install/uninstall smoke test
npm run audit        # F1–F4 regressions + concurrency/lifecycle (16 scenarios)
npm run e2e          # tarball → MCP → daemon → Skills Needed → restore (13 steps)
npm run route -- --explain "make a 30s explainer video"   # try the router

CI (.github/workflows/ci.yml) runs typecheck, tests, smoke, audit, and the end-to-end test on macOS/Windows/Linux × Node 18/20/22, exercises the real installer scripts on each OS, and validates the published tarball installs and runs from a clean environment.

Publishing

The package is a public scoped package (@akbuilds/skillfish-router, publishConfig.access = "public"). prepack/prepublishOnly rebuild dist/, and files ships only dist/ bin/ installers/ + docs (no src/, tests, or dev deps).

Manual publish:

npm login                       # once, as the akcodes9 npm account
npm publish --dry-run           # inspect the tarball (name, files, "public access")
npm publish --access public     # or --provenance from CI (see below)

Then anyone can install with npx @akbuilds/skillfish-router install.

Automated (recommended) — tag-driven semantic versioning:

npm version patch               # bumps package.json + commits + tags vX.Y.Z
git push --follow-tags

.github/workflows/release.yml then guards that the tag matches package.json, runs the full 3-OS × Node-18/20/22 matrix (incl. e2e), publishes to npm with provenance (npm publish --provenance --access public), and cuts a GitHub Release with per-platform artifacts + a SHA256SUMS.txt manifest. Requires an NPM_TOKEN repo secret; provenance uses the workflow's OIDC identity.

License

MIT — see LICENSE.