skillmux
中文文档 / Chinese Documentation

skillmux is a high-performance CLI for managing Skills across multiple remote sources and multiple local runtime targets.
Table of Contents
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:
- Rich search output includes:
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
Development
Build
cargo build
Format, lint, and test
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets
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.