| 💾 Saved. d722711 k33g 6h ago | 1 | # How to add a skill |
| 2 | |
| 3 | 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. |
| 4 | |
| 5 | ## Steps |
| 6 | |
| 7 | 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. |
| 8 | |
| 9 | ```bash |
| 10 | cat > skills/go-test.md <<'EOF2' |
| 11 | --- |
| 12 | name: go-test |
| 13 | description: run the Go tests of the current module and report failures |
| 14 | --- |
| 15 | # Run the Go tests |
| 16 | |
| 17 | Run `go test ./...` with your `bash` tool, then report the failing packages, if any. |
| 18 | EOF2 |
| 19 | ``` |
| 20 | |
| 21 | 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. |
| 22 | |
| 23 | 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. |
| 24 | |
| 25 | 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. |
| 26 | |
| 27 | ## Variants |
| 28 | |
| 29 | - **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. |
| 30 | - **No skills at all.** Leave the directory empty or absent: `read_skill` is then not declared, and the model never sees it. |
| 31 | - **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`. |
| 32 | |
| 33 | ## See also |
| 34 | |
| 35 | - The fields the front matter accepts: [skill file format](../reference/skill-format.md) |
| 36 | - What `read_skill` returns to the model: [built-in tools](../reference/tools.md) |