klhq/skillmux repository overview

One skill vault. Every AI coding agent. Nothing lost in translation.

Every AI coding agent wants its own skill folder and its own format. Skillmux manages SKILL.md⁠ collections across all of them from one place. Keep one vault source of truth (the logical skill collection), pin a small set into native skill directories, and retrieve the rest through MCP. A vault checkout is a physical copy of that collection. On one machine, ~/skills can be both the source of truth and its checkout.

For a shared topology, the Git-backed vault source of truth has a checkout on each agent machine, where the Skillmux CLI creates native pins, and a checkout on the server, where Skillmux server exposes HTTP MCP. Skillmux does not pull, push, replicate, or determine freshness between checkouts; Git and the deployment process own replication and freshness. See native pins with shared retrieval⁠.

The same Skillmux CLI manages native skills and can serve local stdio MCP. Most individual users need only the CLI. Add Docker when you need a shared or always-on HTTP service.

skillmux serve starts local stdio without a config file. skillmux serve --transport http likewise starts on loopback with safe defaults; create a config only when you need to customize the vault, inference, or server policy. See Configuration⁠ and Deployment⁠ for those next steps.

Choose a setup by the job:

1. Need native skills or local MCP for one agent? Install the Skillmux CLI.
2. Want a single file and no package manager? Download the standalone executable; it is the same Skillmux CLI.
3. Need one shared HTTP MCP service? Deploy the full image, the self-contained default with GTE-small.
4. Already have remote embeddings, or intentionally want lexical-only retrieval? Use the slim image; see Deployment⁠.

For native pins and shared retrieval, run the Skillmux CLI on the machines that own agent directories and one shared server for routed retrieval. MCP-only clients connect over HTTP and do not need the Skillmux CLI.

Manage the server's vault checkout outside the container. Use the CLI for Skillmux operations and Git or your deployment process for replication and freshness; server images do not manage host agent directories. If a server image rejects a management command, its error names the host CLI command to run; see the container command contract⁠.

⁠One vault source of truth, three ways to use it

“Local” describes where Skillmux runs. “Local inference” means the embedding model runs in the Skillmux process. Both stdio and HTTP expose the same resolve_skill and fetch_skill MCP tools.

⁠Install the CLI

Skillmux ships as a native executable, so there is no runtime to install alongside it. Any of these works on macOS, Linux, and Windows:

npm install -g @klhapp/skillmux
bun add -g @klhapp/skillmux
npx @klhapp/skillmux --help

Installing pulls exactly one platform-specific executable through optionalDependencies, so you download the build for your machine and not the other four. Native target sync needs permission to create directory symlinks on Windows.

Local embedding inference is included on every platform except Intel macOS. See platform support⁠ for what that costs and why.

You can also install a standalone executable and skip package managers entirely. Every release attaches one per platform. This path needs no GitHub CLI. It selects AMD64 or ARM64, downloads the pinned v1.3.4 release, and verifies the SHA-256 digest published for that release:

version=v1.3.4
case "$(uname -m)" in
  x86_64|amd64) asset=skillmux-linux-amd64; sha256=0d0155475748a937ac9b5878c57e1fa14d8fe6957317cb43bbdafd710cbc1966 ;;
  aarch64|arm64) asset=skillmux-linux-arm64; sha256=8cd186707221a8fefbb79eac46ef14d0c5fdae08a2d76e64a01af17a80af0e06 ;;
  *) echo "Unsupported architecture: $(uname -m)" >&2; exit 1 ;;
esac
bin_dir="${SKILLMUX_BIN_DIR:-$HOME/.local/bin}"
curl --fail --location --output "$asset" "https://github.com/klhq/skillmux/releases/download/$version/$asset"
printf '%s  %s\n' "$sha256" "$asset" | sha256sum --check -
install -Dm755 "$asset" "$bin_dir/skillmux"

Ensure ~/.local/bin is on PATH. To install system-wide, explicitly choose the target: sudo install -Dm755 "$asset" /usr/local/bin/skillmux. For GitHub build-provenance verification, use the attested GitHub CLI procedure⁠. See Deployment⁠ for the full and slim images of Skillmux server.

⁠Quick starts

Skillmux uses ~/skills as its default vault:

~/skills/
└── csv-formatter/
    └── SKILL.md

⁠Manage native skills

Run the setup planner, then verify its managed links:

skillmux init
skillmux sync
skillmux doctor

The planner detects agents, asks which skills belong in the core tier, and shows every write before confirmation. Use explicit flags for automation:

skillmux init \
  --agent claude-code \
  --agent codex \
  --core csv-formatter \
  --dry-run

skillmux init \
  --agent claude-code \
  --agent codex \
  --core csv-formatter \
  --yes

Core pins apply to each configured target and stay capped at 25 skills, or at [core].limit when the manifest sets one. Add project-specific skills from a repository root:

skillmux project init

⁠Add local MCP retrieval

Prefetch the default GTE-small model, index the vault, and start stdio MCP:

skillmux models download
skillmux index
skillmux doctor
skillmux serve

The model cache lives at ~/.cache/skillmux/models. If you skip the prefetch, Skillmux downloads the model when local inference first needs it.

⁠Run a shared MCP service

The full image includes GTE-small and serves Streamable HTTP on /mcp:

docker run -d \
  --name skillmux \
  -v ~/skills:/vault:ro \
  -v skillmux-data:/data \
  -p 3000:3000 \
  ghcr.io/klhq/skillmux:latest

Use ghcr.io/klhq/skillmux:latest-slim when you want remote embeddings or lexical fallback instead of a bundled model. Docker Hub mirrors both variants under docker.io/klhq/skillmux.

The getting-started guide⁠ provides complete recipes for all three setups.

⁠HTTP surfaces

MCP clients authenticate only to /mcp with the MCP bearer token. Operators use a separate administrative bearer token for /admin/v1/*; neither token authorizes the other surface. Named CLI contexts administer the deployed server only. They never install, pin, synchronize, or otherwise manage skill directories on remote agent machines. See Deployment⁠ for configuration and examples.

⁠Add and inspect skills

Install a skill from a Git repository:

skillmux install owner/repo
skillmux install owner/repo/path/to/skill

Skillmux validates SKILL.md and scans candidate content before copying it into the vault, then asks before writing. Pass --yes to approve up front; a non-interactive run needs it, because install refuses to write unattended.

A high-severity finding aborts the install by default. --fail-on low|medium|high|none moves that threshold, and it names the lowest severity that still aborts, so a lower value is stricter: low aborts on low, medium and high, while none installs despite any finding.

Useful management commands:

skillmux scan ~/skills
skillmux outdated
skillmux core pin csv-formatter --yes
skillmux project pin my-project code-context --yes
skillmux skill which csv-formatter
skillmux report --since 7d

Read Managing skills⁠ for target ownership, project groups, local overrides, recovery, and reporting.

⁠MCP retrieval

Register it with an MCP client:

{
  "mcpServers": {
    "skillmux": {
      "command": "skillmux",
      "args": ["serve"]
    }
  }
}

Skillmux exposes two tools:

Skillmux uses the best available capability:

1. SQLite FTS5 provides lexical retrieval and offline fallback.
2. Local or remote embeddings add semantic recall.
3. An optional reranker scores and reorders candidates.

Skillmux returns a ranked shortlist and lets the calling model choose. Endpoint failures degrade to a healthy lower retrieval mode instead of taking the MCP server down.

Read MCP routing⁠ for transports, client instructions, retrieval modes, and the wire contract.

⁠Supported agents

Skillmux preserves existing instruction files and unmanaged target content. Run skillmux init --dry-run to inspect every planned filesystem change.

⁠Guarantees

• Controlled sources: pins come from the configured vault checkout, while routed delivery follows the configured overlay order.
• Scoped writes: management commands write only to documented config, vault, state, and adopted target paths.
• Managed ownership: sync removes only entries recorded in the target's .skillmux marker.
• Current bytes: MCP delivery hashes the file on disk and never serves a stale indexed body.
• Graceful retrieval: embedding and reranker failures fall back without hiding the active capability.
• Auditable decisions: each resolve_skill call records its query, retrieval capability, candidates, scores, and latency in the state database.

⁠Documentation

Start with the documentation hub⁠.

⁠Development

Skillmux uses Bun for development:

bun install --frozen-lockfile
bun test
bun run build

Read CONTRIBUTING.md⁠ for the development workflow and SECURITY.md⁠ for vulnerability reporting.

⁠License

MIT⁠