Skip to main content

​
Overview

Agent Skills are reusable, file-based “playbooks” that you can share across projects or keep workspace-local. Mux follows the Agent Skills specification and exposes skills to models in two steps:
  1. Index in the system prompt: Mux lists available skills (name + description).
  2. Tool-based loading: the agent calls tools to load a full skill when needed.
Skills help you practice progressive disclosure, where the LLM sees only the necessary context to complete the task at hand. The easiest way to invoke a skill in Mux is to use the /<skill-name> slash command. For example: /mux-docs suggest tool hooks for this project. You can find a list of community-maintained, curated skills at skills.sh. You can easily add those skills to your Mux instance with:

​
Where skills live

Mux discovers skills from five roots:
  • Workspace-local: .mux/skills/<skill-name>/SKILL.md (in the workspace working directory)
  • Workspace-local (cross-tool): .agents/skills/<skill-name>/SKILL.md (in the workspace working directory)
  • Global (Mux-specific): ~/.mux/skills/<skill-name>/SKILL.md
  • Universal (cross-tool): ~/.agents/skills/<skill-name>/SKILL.md
  • Built-in: shipped with Mux
If a skill exists in multiple locations, the precedence order is: workspace-local (.mux/skills) > workspace-local (.agents/skills) > global (~/.mux/skills) > universal (~/.agents/skills) > built-in. Built-in skills behave like any other skill for precedence purposes: you can override them by creating a skill with the same name in any higher-precedence workspace-local or global root.
Mux reads skills using the active workspace runtime. For SSH workspaces, skills are read from the remote host.

​
Claude Code compatibility (experiment)

Many repositories already ship skills in Claude Code’s directories. Enable the Claude skills compatibility experiment (Settings → Experiments) to also discover skills from:
  • Workspace-local: .claude/skills/<skill-name>/SKILL.md
  • Global: ~/.claude/skills/<skill-name>/SKILL.md
Compat roots have the lowest precedence within their scope (.mux/skills > .agents/skills > .claude/skills, and likewise for the global roots), and they are read-only: Mux never writes or deletes skills in .claude directories. Skills that package Mux workflow scripts are not discovered from .claude roots.

​
Skill layout

A skill is a directory named after the skill:
Skill directory names must match ^[a-z0-9]+(?:-[a-z0-9]+)*$ (1–64 chars).

​
SKILL.md format

SKILL.md must start with YAML frontmatter delimited by --- on its own line. Mux enforces a 1MB maximum file size for SKILL.md. Required fields:
  • name: must match the directory name
  • description: short summary shown in Mux’s skills index
Optional fields:
  • license
  • compatibility
  • metadata (string key/value map)
  • disable-model-invocation (boolean) — set to true to omit a skill from the system prompt index (see Unadvertised skills below). This spelling is shared with other agent tools such as Claude Code, so portable skills work unchanged.
  • advertise (boolean) — Mux-specific equivalent: advertise: false behaves like disable-model-invocation: true. If both are set, the opt-out wins.
  • user-invocable (boolean) — set to false to hide a skill from user-facing invocation surfaces (see Controlling who invokes a skill).
  • argument-hint (string) — short hint describing the arguments a skill expects (for example [issue-number]), shown next to the skill in invocation UIs (see Skill arguments).
  • when_to_use (string) — extra model-facing guidance appended to the skill’s entry in the skills index. The kebab-case spelling when-to-use is also accepted; the underscore spelling wins if both are set.
Mux ignores unknown frontmatter keys (for example allowed-tools).

​
Controlling who invokes a skill

Two frontmatter fields control a skill’s visibility in opposite directions: Combining them makes a reference-only skill: it is neither indexed for the model nor user-invocable, and only loads when something explicitly calls agent_skill_read({ name: "skill-name" }) — useful for shared fragments referenced by other skills or workflows.

​
Unadvertised skills

By default, Mux advertises skills by listing them in the system prompt’s <agent-skills> index. Set disable-model-invocation: true (or the Mux-specific advertise: false) in the frontmatter to exclude a skill from that index. Unadvertised skills:
  • Are not listed in the system prompt (reducing token overhead)
  • Can still be invoked via /{skill-name} slash command or agent_skill_read({ name: "skill-name" })
  • Still appear in Mux’s UI lists (for example / slash suggestions) and in ACP clients’ command lists
  • Are useful for: skills meant only for sub-agents, advanced users, or internal orchestration

​
Example: deep-review skill

The Mux repository includes an unadvertised deep-review skill that encourages aggressive use of sub-agents to produce excellent code reviews (correctness, tests, consistency, UX, performance). Invoke it with /deep-review when you want a thorough, parallelized review. This skill is defined in .mux/skills/deep-review/SKILL.md.

​
Skill arguments

Slash invocations can carry arguments after the skill name, for example /fix-issue 123 high. If the skill body contains placeholders, Mux substitutes them before the model sees the skill:
  • $ARGUMENTS — the full argument text (123 high)
  • $1 … $9 — whitespace-tokenized positional arguments ($1 is 123); absent positions become empty strings
Substitution rules:
  • Tokenization is simple whitespace splitting; there are no shell quoting rules.
  • Placeholders are substituted everywhere in the body, including code blocks.
  • Only a single digit is consumed: $10 means $1 followed by a literal 0.
  • If the body contains no placeholders, nothing changes: the arguments simply remain visible in your message (for example “Using skill deploy: 123”).
  • Substitution applies only to slash invocations. Inline $skill-name references and model-initiated agent_skill_read loads receive the raw body.
Use the argument-hint frontmatter field to document the expected arguments in invocation UIs.

​
Dynamic context injection (experiment)

Enable the Skill dynamic context injection experiment (Settings → Experiments) to let skills pull live command output into their instructions. When you invoke a skill, any line whose entire content is !`command` runs in the workspace, and the line is replaced with a fenced block containing the command’s output before the model sees the skill:
Rules and limits:
  • Directives must occupy the whole line; mid-line !`...` is ignored.
  • Directives run after argument substitution, so !`git log $1` sees resolved arguments.
  • Commands run sequentially in the workspace directory, with a 10-second timeout and a 16KB output cap per command, and at most 10 directives per skill. A failing command injects its output plus an [exit code N] note instead of aborting the invocation.
  • Directives run only when you invoke a skill (/{skill-name} or a $skill-name reference). Skills the model loads via agent_skill_read always receive the raw body — the model cannot trigger command execution this way.
  • Enabling the experiment requires flipping the toggle in Settings yourself; remote experiment rollout can never switch it on.
Commands come from skill files, which may be committed to the repositories you open. Only enable this experiment if you trust the skills in your projects. Also note that argument substitution runs before directives without shell quoting: a directive like !`git log $1` passes your typed argument to the shell verbatim, so treat skill arguments as shell input when a skill combines placeholders with directives.

​
Current limitations

  • Slash command invocation supports only a single skill as the first token (for example /{skill-name} or /{skill-name} ...).
  • Skill bodies may be truncated when injected to avoid accidental mega-prompts.
  • allowed-tools is not enforced by Mux (it is tolerated in frontmatter, but ignored).

​
Further reading