MusterDocs

Skills

Skills are addons that extend muster with new capabilities — notifications, monitoring, automation. A skill is a folder with a skill.json manifest and a run.sh script.

Browse official skills: github.com/Muster-dev/muster-skills

Quick Start

bash
muster skill create my-skill
# Edit ~/.muster/skills/my-skill/skill.json and run.sh
muster skill run my-skill

Structure

Every skill is a directory containing a manifest and an entry point script. You can optionally include helper scripts in a lib/ folder.

    • skill.json
    • run.sh

skill.json Manifest

The manifest describes your skill and declares its configuration requirements.

Manifest fields

NameDescription
namereq
stringUnique identifier for the skill.
versionreq
stringSemver version string (e.g. "1.0.0").
descriptionreq
stringShort human-readable description of what the skill does.
author
stringAuthor name or GitHub handle.
hooks
string[]Array of hook names to auto-run on (e.g. ["post-deploy", "post-rollback"]).
requires
string[]External commands the skill depends on (e.g. ["curl", "jq"]).
config
object[]Array of config entries the skill needs (see config entries below).

Config entries

NameDescription
keyreq
stringEnvironment variable name exposed to run.sh (e.g. SLACK_WEBHOOK_URL).
label
stringHuman-readable label shown during configuration prompts.
hint
stringHelp text or example value shown alongside the prompt.
secret
booleanWhen true, the value is masked during input and stored securely. Default: false

Users configure a skill with muster skill configure <name>, which saves values to config.env. This file is auto-loaded before run.sh executes.

run.sh

The entry point script receives environment variables from muster and any config values from config.env.

Environment variables

NameDescription
MUSTER_SERVICE
stringName of the service being deployed.
MUSTER_SERVICE_NAME
stringDisplay name of the service.
MUSTER_HOOK
stringThe hook that triggered this run (e.g. "post-deploy").
MUSTER_DEPLOY_STATUS
stringDeploy outcome: "success", "failed", or "skipped".
MUSTER_PROJECT_DIR
stringAbsolute path to the project root.
MUSTER_CONFIG_FILE
stringPath to the muster.json config file.
Note
Exit 0 means success, non-zero means failure. Muster warns on failure and continues — a skill will never block a deploy.

Hooks

Skills can hook into deploy lifecycle events. List the hooks you want in the hooks array of skill.json.

Service hooks

NameDescription
pre-deploy
hookFires before each service deploys.
post-deploy
hookFires after each service (success, failed, or skipped).
pre-rollback
hookFires before a service rollback.
post-rollback
hookFires after a service rollback.

Hook execution is non-fatal — a failing skill never blocks or modifies your deploy. The MUSTER_DEPLOY_STATUS variable tells you whether the deploy succeeded, failed, or was skipped.

Tip
Skills must be enabled to auto-run on hooks. After configuring, run muster skill enable <name> to activate.

Fleet Hooks

Skills can also fire during fleet operations for multi-machine deploys.

Fleet hooks

NameDescription
fleet-deploy-start
hookBefore a fleet deploy begins.
fleet-deploy-end
hookAfter a fleet deploy finishes.
fleet-machine-deploy-start
hookBefore deploying to each machine in the fleet.
fleet-machine-deploy-end
hookAfter deploying to each machine in the fleet.
fleet-rollback-start
hookBefore a fleet rollback begins.
fleet-rollback-end
hookAfter a fleet rollback finishes.

Fleet environment variables

NameDescription
MUSTER_FLEET_NAME
stringName of the fleet being deployed.
MUSTER_FLEET_MACHINE
stringCurrent machine identifier.
MUSTER_FLEET_HOST
stringHostname or IP of the current machine.
MUSTER_FLEET_STRATEGY
stringDeploy strategy for the fleet (e.g. rolling, parallel).
MUSTER_FLEET_MODE
stringFleet operation mode.
MUSTER_DEPLOY_STATUS
stringDeploy outcome: "success", "failed", or "skipped".

Per-fleet skill configuration is managed separately with muster fleet skill enable/configure/disable.

Skill Lifecycle

The full lifecycle of a skill follows four stages:

1

Install

Add the skill from the marketplace, a git URL, or a local path.

2

Configure

Set API keys, webhooks, and other required values.

3

Enable

Turn on auto-run so the skill fires on configured hooks.

4

Auto-runs

The skill runs automatically on matching hooks (or run manually at any time).

All Commands

bash
muster skill marketplace          # browse and install from registry
muster skill add <url-or-path>    # install from git URL or local path
muster skill configure <name>     # set API keys, webhooks, etc.
muster skill enable <name>        # turn on auto-run
muster skill disable <name>       # turn off auto-run
muster skill run <name>           # run manually
muster skill list                 # show installed skills
muster skill remove <name>        # uninstall
muster skill create <name>        # scaffold new skill

Marketplace

Browse, search, and install skills from the official registry using the built-in TUI interface. Search by name or description.

bash
# Browse the marketplace
muster skill marketplace

# Install from a git URL (muster-skill- prefix is auto-stripped)
muster skill add https://github.com/yourname/muster-skill-ssl

# Install from a local path
muster skill add /path/to/my-skill

# Install globally instead of per-project
muster skill --global marketplace
Tip
When installing from a git URL, the muster-skill- prefix is automatically stripped from the skill name, so muster-skill-ssl becomes just ssl.

Publishing

There are two ways to publish a skill:

  • Option A: Own repository — Create a repo named muster-skill-<name>. Place skill.json and run.sh at the repository root. Anyone can install it directly with muster skill add.
  • Option B: Official registry — Submit to the official registry at github.com/Muster-dev/muster-skills. Fork the repo, add your skill folder and a registry.json entry, then open a pull request.
Fleet & CloudMCP Integration