Skillmux documentation for coding-agent skill profiles

First-time setup

Run init once per machine. It discovers your agent skill folders, backs them up, and relinks them through the active profile. Use --dry-run to preview what will change before committing.

Preview first

$ skillmux init --profile work --dry-run

Apply

$ skillmux init --profile work --yes

After init, ~/.claude/skills, ~/.codex/skills, and ~/.agents/skills point to the work profile. Skills installed by any agent tool land in that profile instead of a global folder.

Create profiles

A profile is a named set of skills. Create one for each context you work in — work, frontend, research, writing. Profiles are stored under ~/.skillmux/profiles/.

# create a new empty profile
$ skillmux profile create research

# list all profiles
$ skillmux profile list

# inspect what's in a profile
$ skillmux profile show research

You can also create a profile and switch to it in one command with the --create flag on use:

$ skillmux use research --create

Switch profiles

use relinks all agent skill folders to a different profile in a single command. All agents — Claude, Codex, and .agents — update at once.

# switch all agents to the research profile
$ skillmux use research

# confirm what's active
$ skillmux current
research

Work vs personal

The most common setup: one profile for work projects, another for personal ones. Skills that contain proprietary context, internal tooling, or sensitive commands stay isolated in the work profile and never bleed into personal sessions.

# morning — start work
$ skillmux use work

# evening — switch to personal projects
$ skillmux use personal

Each profile maintains its own copy of skills under ~/.skillmux/profiles/. Installing a skill while work is active puts it in the work profile only.

Per-project profile pins

Add a .skillmux.toml to any project root to declare which profile it uses. Run skillmux enter when you cd into the project and your agents switch automatically.

# .skillmux.toml
profile = "frontend"
agents  = ["claude", "codex"]

# activate the pinned profile for this project
$ skillmux enter

# create the profile if it doesn't exist yet
$ skillmux enter --create

enter reads the nearest .skillmux.toml and calls use with the declared profile and agents. You can automate it from your shell's chpwd hook or a cd wrapper to switch profiles whenever you change directories.

Agent-specific switching

Switch a single agent to a different profile without affecting the others. Useful when you want Claude on one profile while Codex stays on another.

# move only codex to the work profile
$ skillmux use work --agent codex

# check the current state per agent
$ skillmux current

Inspect & scan

Use scan to list every skill in a profile. Use doctor to verify that your managed folders are healthy and linked correctly.

# list skills in a profile
$ skillmux scan --profile work

# verify all links are intact
$ skillmux doctor

# show the active profile
$ skillmux current

Backup & recovery

Skillmux writes a TOML backup manifest before every operation that touches managed folders. You can take manual snapshots and restore any of them by ID.

# take a manual backup
$ skillmux backup

# list all backups
$ skillmux backup list

# restore a specific backup
$ skillmux restore <backup-id> --yes

# attempt automatic repair
$ skillmux repair --dry-run
$ skillmux repair

# fully remove skillmux and restore original folders
$ skillmux uninstall --yes

uninstall restores the most recent pre-init backup by default. Pass --backup-id to target a specific snapshot. The ~/.skillmux directory is kept for audit after uninstall.

Shell completions

Skillmux ships Cobra completions for subcommands, flags, profile names, agent names, and backup IDs.

Load for the current session

$ source <(skillmux completion zsh)
$ source <(skillmux completion bash)
$ skillmux completion fish | source

Install permanently

# zsh (Homebrew)
$ skillmux completion zsh > "$(brew --prefix)/share/zsh/site-functions/_skillmux"

# bash (Homebrew)
$ skillmux completion bash > "$(brew --prefix)/etc/bash_completion.d/skillmux"

# fish
$ skillmux completion fish > ~/.config/fish/completions/skillmux.fish