SkillMux Zack Zhu

agent automation cli developer-tools skill skills

Use this command to install SkillMux:

winget install --id=ZackZhu.SkillMux -e

SkillMux is a high-performance CLI for managing skills across multiple remote sources and multiple local runtime targets.

skillmux

中文文档 / Chinese Documentation

skillmux is a high-performance CLI for managing Skills across multiple remote sources and multiple local runtime targets.

What is skillmux

Modern agent runtimes often need skills from different ecosystems (official registries, internal hubs, GitHub repos), and they may store those skills in different local folders.

skillmux solves this by providing:

One unified CLI for search / install / list / update / remove.
Multiple source backends in one tool.
Multiple target layouts for different agent products.
Reproducible metadata tracking for installed skills.

Core Capabilities

1) Multi-source skill discovery

Search skills from configured source providers.
Built-in source adapters include:
- kingdee
- clawhub
Rich search output includes:
- slug
- version
- description

2) Flexible install flows

Install from:

Named skill slug from configured source.
GitHub shorthand:
- gh:owner/repo
- github:owner/repo
Full GitHub repository URL.

Optional install controls:

--version to pin a version when source supports versioning.
--ref to install from a specific git ref.
--subdir to install from a repository subdirectory.
--as to rename the local installed folder.
--force to overwrite/refresh existing content.
--json for machine-readable output.

For registry sources, the local folder name defaults to the skill slug. Display names from SKILL.md are saved as metadata, which avoids duplicate installs when a skill has a localized display name.

3) Rich local inventory

skillmux list shows installed skills with metadata such as:

target
local skill name
source
version
description

4) Safe updates

Update one installed skill by name.
Update all installed skills with --all or with no update argument.
Shows per-skill installed / updated / unchanged status instead of repeated install logs.
Keeps source information to make update behavior deterministic.

5) Clean removal

Remove a skill from managed targets.
Optional purge mode for deeper cleanup.

6) Multi-target support

Supports target-specific install layouts, including:

codex
qoder
qoderwork
kiro
workbuddy

Installation

Via pip

pip install skillmux

Verify installation

skillmux --version

Command Overview

Search

skillmux search  [--limit ] [--page ] [--json]

Install

skillmux install 
  [--version ]
  [--ref ]
  [--subdir ]
  [--as ]
  [-y|--yes]
  [--force]
  [--json]

List

skillmux list [--json]

Update

skillmux update [skill]
skillmux update --all [--ref ]

Remove

skillmux remove  [--purge]

Config

skillmux config list
skillmux config get 
skillmux config set  
skillmux config targets 
skillmux config targets set 
skillmux config targets add 
skillmux config targets remove

Configuration

skillmux reads settings from config and command-line overrides.

Common configuration dimensions:

API endpoint and timeout.
Default source.
Install targets.
Token resolution strategy.

CLI-level override flags:

--config : use a specific config file.
--api : override API endpoint.
--token : provide token for the current run.
--source : override default source.

Source Resolution Rules

When installing:

If input looks like GitHub shorthand/URL, it is handled by GitHub flow.
Otherwise it is resolved through the currently selected source backend.
Source metadata is persisted for future updates.

This design allows predictable updates even when multiple sources may contain similarly named skills.

Install Targets

Each target maps to a specific local directory layout.

Why this matters:

Different agent products discover skills in different paths.
skillmux normalizes install/update/remove operations across these paths.

Recommended workflow:

Configure the target list once.
Install skills normally.
Use list and update --all for routine maintenance.

Examples

Basic flow

skillmux search pdf
skillmux install pdf-processing
skillmux list
skillmux update --all
skillmux remove pdf-processing

Install from GitHub

skillmux install gh:owner/repo
skillmux install https://github.com/owner/repo

Install from subdirectory at a ref

skillmux install gh:owner/repo --ref v1.2.3 --subdir skills/my-skill --as my-skill

JSON output for automation

skillmux search retrieval --json
skillmux list --json

Troubleshooting

Skill not found

Confirm source selection (--source or config default).
Retry with a broader search keyword.

Update fails for one skill

Check whether the original source is still reachable.
If source changed, remove and reinstall from desired source.

Target mismatch

Verify configured targets:
```
skillmux config get install.targets
```

Development

Build

cargo build

Format and check

cargo fmt
cargo check

Release

The release helper keeps Cargo.toml and pyproject.toml in sync, commits the version bump, creates an annotated tag, pushes the branch and tag, then creates a GitHub release with generated notes.

Interactive:

python scripts/release.py

Non-interactive:

python scripts/release.py patch --yes
python scripts/release.py major --yes

PowerShell:

.\scripts\release.cmd patch --yes

Use --dry-run to preview the release. The script requires a clean git worktree, git, and an authenticated GitHub CLI (gh auth status).

The publish GitHub Actions workflow runs when a GitHub Release is published. It builds PyPI wheels and standalone CLI binaries for:

x86_64-unknown-linux-gnu
aarch64-unknown-linux-gnu
x86_64-pc-windows-msvc
aarch64-pc-windows-msvc
x86_64-apple-darwin
aarch64-apple-darwin

The workflow uploads the standalone CLI binaries plus SHA256SUMS.txt to the same GitHub Release and publishes wheels to PyPI. After that, it updates packaging/winget metadata on the default branch; that metadata commit triggers the publish-winget workflow, which submits the WinGet update with WingetCreate.

WinGet automation requires PACKAGING_METADATA_TOKEN to be a PAT or GitHub App token that can push to this repository and trigger workflows. It also requires WINGET_CREATE_GITHUB_TOKEN for WingetCreate submission. Set WINGET_RELEASE_REPOSITORY only if the GitHub Release assets live in a different repository than the one already recorded in packaging/winget.

License

Released under the terms of the repository license.