> ## Documentation Index
> Fetch the complete documentation index at: https://mux-agent-plugin-install-ux.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Skills

> Share reusable workflows and references with skills

## 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](https://skills.sh/).

You can easily add those skills to your Mux instance with:

```bash theme={null}
npx skills add https://github.com/anthropics/skills --skill frontend-design
```

## 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.

<Info>
  Mux reads skills using the active workspace runtime. For SSH workspaces, skills are read from the
  remote host.
</Info>

### 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.

### Agent Plugins (experiment)

Enable the **Agent Plugins** experiment (Settings → Experiments) to also discover skills packaged in [Agent Plugins 1.0.0](https://agent-plugins.org) directories — a plugin is a directory with a `plugin.json` manifest plus an optional `skills/` folder. Plugins are discovered from:

* **Workspace-local**: `.mux/plugins/<plugin>/` and `.agents/plugins/<plugin>/`
* **Global**: `~/.mux/plugins/<plugin>/` and `~/.agents/plugins/<plugin>/`

Plugin skills have the lowest precedence within their scope and are read-only. A broken plugin (or a broken skill inside one) never affects other plugins or skills. Plugins can also ship MCP servers; see [MCP servers](/config/mcp-servers#agent-plugins-servers-experiment).

Global plugins can be installed from git via **Settings → Plugins** (paste a git URL or `owner/repo[@ref]`); the install preview lists every skill the plugin would contribute before anything is written.

## Skill layout

A skill is a directory named after the skill:

```text theme={null}
.mux/skills/
  my-skill/
    SKILL.md
    references/
      ...
```

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](#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](#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](#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:

| Field                                                 | Hides the skill from                                                                                 | Still works via                                                   |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `disable-model-invocation: true` (`advertise: false`) | The model-facing skills index                                                                        | `/{skill-name}`, `$skill-name`, `agent_skill_read({ name: ... })` |
| `user-invocable: false`                               | User-facing surfaces: `/` menu and typed `/{skill-name}`, `$` references, command palette, ACP lists | Model auto-invocation via the skills index                        |

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`.

```md theme={null}
---
name: deep-review
description: Sub-agent powered code reviews spanning correctness, tests, consistency, and fit
advertise: false
---

# Deep Review Mode

Provide an **excellent code review** by defaulting to **parallelism**.

You should use sub-agents to review the change from multiple angles (correctness, tests, consistency, UX, performance, safety). Each sub-agent should have a focused mandate and return actionable findings with file paths.

## Step 0: Establish the review surface

Before reviewing, gather context:

- Identify the change scope: `git diff --name-only` (or the file list the user provides).
- Skim the diff for intent and risk: `git diff`.
- Note which layers are touched:
  - UI (React/components/styles)
  - Main process / backend services
  - IPC boundary / shared types
  - Tooling/scripts
  - Docs
  - Tests

If the change is large, split review by module and prioritize **high-risk** paths.

## Spawn the right sub-agents (change-type aware)

Spawn **2–5** sub-agents depending on scope. Tailor them to the change.

### Suggested sub-agent set

- **Correctness & edge cases** (always)
  - Goal: find logic bugs, missing error handling, race conditions, broken invariants.
- **Tests & verification** (always)
  - Goal: evaluate test coverage, propose missing tests, suggest commands to validate.
- **Consistency & architecture** (usually)
  - Goal: ensure changes match existing patterns, abstractions, and boundaries.
- **UX & accessibility** (when UI changed)
  - Goal: keyboard flows, a11y, visual consistency, empty/loading/error states.
- **Performance & reliability** (when hot paths / streaming / IO changed)
  - Goal: latency, unnecessary work, blocking calls, memory growth, resilience.
- **Docs & developer experience** (when docs/scripts/public API changed)
  - Goal: clarity, correctness, navigation updates, link integrity.

## Synthesize into a single excellent review

When sub-agent results arrive, produce a consolidated review with:

1. **Summary** (what changed + overall risk)
2. **Issues**
3. **Questions** (unknown intent; ask for clarification)
4. **Suggested validation plan** (commands + manual checks)

Issues should have a severity in form of:

| Severity | Description                              | Example                                                                                       |
| -------- | ---------------------------------------- | --------------------------------------------------------------------------------------------- |
| P0       | Change must not be merged until resolved | Change would permanently break core workflows if merged.                                      |
| P1       | Change should not be merged              | New code will not work as expected due to severe bugs                                         |
| P2       | Consideration required before merging    | The change creates inconsistency / fragility                                                  |
| P3       | Minor issue                              | The change introduces a minor issue that may be addressed later                               |
| P4       | Long-term issue                          | The change raises concerns about long-term maintainability or may break under rare conditions |

### Review rubric

Use this rubric to avoid blind spots:

- **Correctness**: invariants, edge cases, error handling, races
- **Fitness**: does it meet the user goal, and does it match product constraints?
- **Tests**: coverage of new logic, regression tests, deterministic behavior
- **Consistency**: patterns, naming, types, boundaries, IPC typing
- **Maintainability**: complexity, duplication, readability
- **Performance**: hot paths, streaming, excessive re-renders/IO
- **Safety**: secrets, path traversal, injection risks, filesystem safety
- **DX**: logs, error messages, debuggability

## Anti-patterns

- **Single-threaded review** of a large change (spawn sub-agents).
- **Vague feedback** (“looks good”) without actionable items and file paths.
- **Non-verifiable suggestions** (always include a validation plan).
- **Scope creep** disguised as review (focus on minimal changes unless risk demands more).
```

## 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:

```md theme={null}
---
name: summarize-changes
description: Summarize uncommitted changes and flag risks
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above and list any risks you notice.
```

Rules and limits:

* Directives must occupy the whole line; mid-line `` !`...` `` is ignored.
* Directives run after [argument substitution](#skill-arguments), 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.

<Warning>
  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](#skill-arguments) 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.
</Warning>

## 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

* [Agent Skills overview](https://agentskills.io/home)
* [What are skills?](https://agentskills.io/what-are-skills) (progressive disclosure)
* [Agent Skills specification](https://agentskills.io/specification)
  * [Directory structure](https://agentskills.io/specification#directory-structure)
  * [`SKILL.md` format](https://agentskills.io/specification#skill-md-format)
  * [Frontmatter fields](https://agentskills.io/specification#frontmatter-required)
  * [Optional directories](https://agentskills.io/specification#optional-directories)
  * [Progressive disclosure](https://agentskills.io/specification#progressive-disclosure)
* [Integrate skills into your agent](https://agentskills.io/integrate-skills) (tool-based vs filesystem-based)
* [Example skills (GitHub)](https://github.com/anthropics/skills)
* [skills-ref validation library (GitHub)](https://github.com/agentskills/agentskills/tree/main/skills-ref)