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.

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

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.

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

Skill layout

A skill is a directory named after the skill:

.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)
• advertise (boolean) — set to false to omit a skill from the system prompt index (see Unadvertised skills below)

Mux ignores unknown frontmatter keys (for example allowed-tools).

Unadvertised skills

By default, Mux advertises skills by listing them in the system prompt’s <agent-skills> index.

Set 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)
• 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.

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

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
• What are skills? (progressive disclosure)
• Agent Skills specification
  • Directory structure
  • SKILL.md format
  • Frontmatter fields
  • Optional directories
  • Progressive disclosure
• Integrate skills into your agent (tool-based vs filesystem-based)
• Example skills (GitHub)
• skills-ref validation library (GitHub)