> ## Documentation Index
> Fetch the complete documentation index at: https://mux-advisor-cache-dt21.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.

Xum follows the Agent Skills specification and exposes skills to models in two steps:

1. **Index in the system prompt**: Xum 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 Xum is to use the `/<skill-name>` slash command. For example:
`/xum-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 Xum instance with:

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

## Where skills live

Xum discovers skills from these locations:

* **Project**: `.xum/skills/<skill-name>/SKILL.md`
* **Project (cross-tool)**: `.agents/skills/<skill-name>/SKILL.md`
* **Global (Xum-specific)**: `~/.xum/skills/<skill-name>/SKILL.md`
* **Universal (cross-tool)**: `~/.agents/skills/<skill-name>/SKILL.md`
* **Built-in**: shipped with Xum

For a workspace that executes in a subproject, Xum checks the working directory and each parent directory through the checkout root. It never searches above the checkout. A nearer project definition wins over a farther one; within the same directory, `.xum/skills` wins over `.agents/skills`.

Legacy `.mux/skills` directories remain readable after `.xum/skills` at the same directory level. New and updated project skills are written only to `.xum/skills`.

After project skills, the remaining precedence order is **global (`~/.xum/skills`) > universal (`~/.agents/skills`) > built-in**. Built-in skills behave like any other skill for precedence purposes, so any project or global skill with the same name overrides them.

<Info>
  Xum 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 compatibility** experiment (Settings → Experiments) to also discover skills from:

* **Workspace-local**: `.claude/skills/<skill-name>/SKILL.md`
* **Global**: `~/.claude/skills/<skill-name>/SKILL.md`

Within the same directory, compat roots have the lowest precedence (`.xum/skills` > `.agents/skills` > `.claude/skills`); a nearer directory still wins over a farther one. The global roots use the same convention order. Compat roots are read-only: Xum never writes or deletes skills in `.claude` directories. Skills that package Xum 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**: `.xum/plugins/<plugin>/` and `.agents/plugins/<plugin>/`
* **Global**: `~/.xum/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 preview lists the full package before anything is written. Select which skills and MCP servers to import; both groups start with all current items selected and support **Select all** and **Clear**. You can install with neither group selected. Agents, workflows, slash commands, and hooks are unaffected by this choice; review their disclosures too. Imported MCP servers remain disabled until you enable them per workspace.

Installed rows show imported-of-available counts. For a managed, present plugin, choose **Add components** (or **Add Plugin Components…** in the command palette) to import more from its locked installed version without fetching the remote. Previously imported components are checked and read-only. Select additions and confirm, or cancel without changing anything. If the installed version changes during review, the inventory refreshes and you must select again. Removing imports is not supported by this flow.

Updates preserve explicit selections: newly available skills and MCP servers stay unimported until you add them. Updates still require consent for full-package capability changes, including unimported components. Older managed installs without a saved selection continue importing everything, including new components on update. Unmanaged and project-local plugins are unchanged.

<Warning>
  Import selection controls discovery, not filesystem access: skipped files remain in the plugin
  directory and can still be read. It is not a filesystem sandbox. Older Xum versions may ignore the
  selection field and expose every component. Losing the install registry also loses selection; the
  remaining directory cannot be distinguished from an unmanaged plugin and may expose everything.
</Warning>

## Skill layout

A skill is a directory named after the skill:

```text theme={null}
.xum/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.
Xum enforces a 1MB maximum file size for `SKILL.md`.

Required fields:

* `name`: must match the directory name
* `description`: short summary shown in Xum’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) — Xum-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.

Xum 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, Xum *advertises* skills by listing them in the system prompt’s `<agent-skills>` index.

Set `disable-model-invocation: true` (or the Xum-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 Xum’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 Xum 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 `.xum/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, Xum 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 Xum (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)