How to add a skill

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

# How to add a skill

This guide shows how to give the agent a new markdown procedure that the model can load with `read_skill`. It assumes you know what task the procedure should cover.

## Steps

1. Create the skill in the skills directory (`skills/` by default, see `skillsDir`), in either layout: a flat file `skills/<name>.md`, or a directory per skill `skills/<name>/SKILL.md` (the layout of the shipped examples). The two can be mixed; any other file in a skill's directory is ignored.

   ```bash
   cat > skills/go-test.md <<'EOF2'
   ---
   name: go-test
   description: run the Go tests of the current module and report failures
   ---
   # Run the Go tests

   Run `go test ./...` with your `bash` tool, then report the failing packages, if any.
   EOF2
   ```

2. Give it a `name:` and a one-line `description:` in the front matter. The description is what the model reads in the `read_skill` tool description to pick a skill; without one it chooses blindly.

3. Restart `mm`. The catalogue is built once at start-up. The banner's `skills: N` counter goes up by one, and `read_skill` appears in the `tools:` list if it was absent.

4. Ask for the task in the terminal. The system prompt in `agent.yaml` tells the model to call `read_skill` first for any request that matches the catalogue; a `📖 read_skill: go-test` line confirms it did.

## Variants

- **Another directory.** Set `skillsDir` in the YAML. In the terminal a relative path is resolved from the directory you start `mm` in, so an installed `mm` run inside a project loads that project's skills; in ACP mode with a config file it is resolved next to that file. The banner prints `[warning: no skills found in <absolute path> …]` when the resolved directory yields nothing.
- **No skills at all.** Leave the directory empty or absent: `read_skill` is then not declared, and the model never sees it.
- **The shipped examples.** The repository ships `skills/greetings/SKILL.md`, `skills/vulcan-salute/SKILL.md` and `skills/what-time-is-it/SKILL.md`. Start `mm` from the repository root and the banner shows `skills: 3`.

## See also

- The fields the front matter accepts: [skill file format](../reference/skill-format.md)
- What `read_skill` returns to the model: [built-in tools](../reference/tools.md)