Skills

Skills are reusable instruction sets that an agent can load on demand. Each skill lives in its own directory containing a SKILL.md file.

Discovery paths

Skills are discovered from these locations, in order of precedence (earlier wins on a name collision):

1. <cwd>/.muaz/skills/ and <cwd>/.agents/skills/ — project-level
2. ~/.muaz/plugins/local/skills/ — your local workspace (user-level)
3. installed plugin skills/ directories
4. built-in skills/ directories

Local and project skills are trusted automatically. A plugin skill’s allowed-tools are pre-approved only when the plugin is trusted; otherwise its tools prompt on use like any other tool.

SKILL.md format

---
name: my-skill
description: A short description shown in listings
compatibility: muaz>=1.0     # optional
allowed-tools: shell:git * fetch_webpage:*  # optional; space-separated tool patterns
---

# my-skill

Full skill instructions go here. The agent reads this file when it wants to use
the skill.

How agents select skills

Skills are opt-in by explicit selection — an agent is never handed every discovered skill automatically. An agent lists the skills it uses in its config, and each name is resolved against the discovery paths above (local → plugins → built-ins). A name that resolves to nothing produces a warning when the agent loads, so a typo or a missing plugin surfaces instead of failing silently.

# in the agent's YAML
skills:
  allow:               # the skills this agent uses, by name
    - verify-and-debug
  paths: []            # optional extra skill directories (relative to this file)

With no skills: block — or an empty allow list — the agent gets no skills, even ones shipped in its own plugin.

For each selected skill, an ## Available Skills block is appended to the agent’s system prompt listing its name, description, and SKILL.md path. The agent reads the file when it decides to invoke the skill.

Managing skills from the CLI

muaz skills list               # show all discovered skills with scope
muaz skills create             # interactive wizard to create a new skill
muaz skills show my-skill      # print the SKILL.md of a skill
muaz skills edit my-skill      # open SKILL.md in $EDITOR

From inside the REPL, /skills lists available skills and /skill <name> prints a skill’s SKILL.md.