Skip to main content

​
Overview

Agent Skills are reusable, file-based “playbooks” that you can share across projects or keep project-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.
This keeps the system prompt small while still making skills discoverable.

​
Where skills live

Mux discovers skills from three roots:
  • Project-local: <projectRoot>/.mux/skills/<skill-name>/SKILL.md
  • Global: ~/.mux/skills/<skill-name>/SKILL.md
  • Built-in: shipped with Mux
If a skill exists in multiple locations, the precedence order is: project-local > global > built-in.
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)
Mux ignores unknown frontmatter keys (for example allowed-tools). Example: 
---
name: my-skill
description: Build and validate a release branch.
license: MIT
metadata:
  owner: platform
---

# My Skill

1. Do the thing...

​
Using skills in Mux

Mux injects an <agent-skills> block into the system prompt listing the available skills. You can apply a skill in two ways:
  • Explicit (slash command): type /{skill-name} (optionally followed by a message: /{skill-name} ...) in the chat input. Mux will send your message normally (or a small default message if you omit one), and persist a synthetic snapshot of the skill body in history immediately before that message.
    • Example: /init runs the built-in init skill to bootstrap AGENTS.md. You can override it with ~/.mux/skills/init/SKILL.md (or .mux/skills/init/SKILL.md for a single project).
    • Type / to see skills in the suggestions list.
  • Agent-initiated (tool call): the agent can load skills on-demand.
To load a skill, the agent calls: 
agent_skill_read({ name: "my-skill" });
If your skill references additional files (cheatsheets, templates, etc.), the agent can read them with: 
agent_skill_read_file({ name: "my-skill", filePath: "references/template.md" });
agent_skill_read_file supports offset / limit (like file_read) and rejects absolute paths and .. traversal.
agent_skill_read_file uses the same output limits as file_read (roughly 16KB per call, numbered lines). Files are limited to 1MB. Read large files in chunks with offset/limit.

​
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