Skip to main content

​
Overview

Agent Skills are reusable, file-based “playbooks” that you can share across projects or keep workspace-local. Shux follows the Agent Skills specification and exposes skills to models in two steps:
  1. Index in the system prompt: Shux 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 Shux is to use the /<skill-name> slash command. For example: /shux-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 Shux instance with:

​
Where skills live

Shux discovers skills from these locations:
  • Project: .mux/skills/<skill-name>/SKILL.md
  • Project (cross-tool): .agents/skills/<skill-name>/SKILL.md
  • Global (Shux-specific): ~/.shux/skills/<skill-name>/SKILL.md
  • Universal (cross-tool): ~/.agents/skills/<skill-name>/SKILL.md
  • Built-in: shipped with Shux
For a workspace that executes in a subproject, Shux 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, .mux/skills wins over .agents/skills. After project skills, the remaining precedence order is global (~/.shux/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.
Shux 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
Within the same directory, compat roots have the lowest precedence (.mux/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: Shux never writes or deletes skills in .claude directories. Skills that package Shux 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 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: ~/.shux/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.

​
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. Shux enforces a 1MB maximum file size for SKILL.md. Required fields:
  • name: must match the directory name
  • description: short summary shown in Shux’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) — Shux-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.
Shux 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, Shux advertises skills by listing them in the system prompt’s <agent-skills> index. Set disable-model-invocation: true (or the Shux-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 Shux’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 Shux 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, Shux 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 Shux (it is tolerated in frontmatter, but ignored).

​
Further reading