Tutorial 6 Customizing malac

Tutorial 6: Customizing malac

Write an agent type and a skill, connect MCP servers, and change settings by asking malac.

malac is customized with plain files and a few lines of TOML. In this tutorial you add a reviewer subagent, a skill, standing instructions and an MCP server, and then change settings simply by asking.

You need malac from tutorial 1 and the shop project from tutorial 2 (any git repository works). The MCP part needs Node.js for npx.

An agent type

1. Create a reviewer. In the shop repository:

   mkdir -p .malac/agents
   cat > .malac/agents/reviewer.md <<'EOF'
   ---
   name: reviewer
   description: Reviews uncommitted changes for bugs, missing tests and unclear code
   tools: read, grep, glob, bash
   ---
   You review the uncommitted changes in this repository. Start with `git diff` and
   `git status`, then read enough of the surrounding code to judge each change in context.
   
   Report only real problems, most severe first. For each one give the file and line,
   what goes wrong and in which situation, and a concrete fix. Skip style preferences the
   codebase does not already follow. If the change looks correct, say so in one sentence.
   
   Do not modify any files.
   EOF

   The description is what the agent sees when it decides whom to delegate to. tools limits the reviewer to reading, searching and the shell.

2. Make a change worth reviewing.

   sed -i.bak 's/rate=0.27/rate=27/' tax.py && rm tax.py.bak

3. Ask for a review.

   malac --plain have the reviewer look at my uncommitted changes

   ● agent_spawn reviewer: Review the uncommitted changes in this repository…
     ↳ reviewer started (lora/default)
   
   ? [reviewer] bash git diff
     [y] allow  [a] always  [n] deny  allowed
     ↳ reviewer · bash git diff
     ↳ reviewer · read tax.py
     ↳ reviewer · grep with_vat
     ✓ reviewer finished
   The reviewer found one problem: tax.py:3 changes the default VAT rate from
   0.27 to 27, so with_vat([100.0]) returns 2800.0 instead of 127.0 …
   

   The reviewer's own permission prompts are labelled [reviewer]. Its type lives in the project, so everyone who clones the repository gets it. Put types you want everywhere in ~/.malac/agents/.

4. Undo the change: git checkout tax.py.

A skill

1. Write a skill for a task you repeat. Skills live in their own folder:

   mkdir -p ~/.malac/skills/release-notes
   cat > ~/.malac/skills/release-notes/SKILL.md <<'EOF'
   ---
   name: release-notes
   description: Write release notes from the git log since the last tag
   ---
   # Release notes
   
   1. Find the last tag with `git describe --tags --abbrev=0`. With no tags, use the whole history.
   2. Collect commits since then with `git log <tag>..HEAD --oneline`.
   3. Group them under Added, Changed and Fixed. Drop merge commits and chores.
   4. Print the notes. Do not write any file unless asked.
   EOF

2. Use it. Skills are read when a tab loads, so start a fresh one (this command opens a new tab in the daemon) and ask:

   malac --plain write release notes for this repo

   ● skill release-notes
   ● bash git describe --tags --abbrev=0
     ⎿ fatal: No names found, cannot describe anything.
   ● bash git log --oneline
   ## Added
   - Shop package with cart, pricing and VAT
   …
   

   The skill's name and description are in the system prompt; the agent loaded it with the skill tool because the task matched. /release-notes runs it directly. Skills in ~/.claude/skills/, .agents/skills/ and the project's .claude/skills/ are picked up too, and a skill can ship scripts next to its SKILL.md; see Skills.

Standing instructions

Rules for every task in a project go in AGENTS.md at the repository root:

cat > AGENTS.md <<'EOF'
- Run `python3 -m unittest -q` before saying a change is done.
- Keep functions small and typed; no new dependencies without asking.
EOF

malac reads it at the start of every session in this repository, along with the instruction files other agents use (CLAUDE.md, GEMINI.md, Cursor and Copilot rules, …). A file in ~/.malac/AGENTS.md applies to every project. /context shows what was loaded; see Project context.

MCP servers

1. Add a local MCP server. This one gives the agent tools for a notes folder. In ~/.malac/config.toml (MCP servers can only be added in your user configuration):

   [mcp.notes]
   command = "npx"
   args = ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/notes"]

   mkdir -p ~/notes && echo "Pick up oat milk." > ~/notes/todo.md

2. Check the connection.

   malac mcp

   ● notes (14 tools)
   ● control (28 tools)
   
   notes__read_file, notes__list_directory, …, computer_screenshot, …
   

   The server's tools are prefixed with its name, so they never clash. The tool count depends on the server's version.

3. Use it, and allow it. Ask "what is on my todo list in my notes?". The first notes__… call asks for permission (MCP tools are Execute tools unless the server marks them read-only). To allow the whole server without asking, add a rule:

   [permissions]
   allow = ["notes__*"]

4. A remote server works the same way, over streamable HTTP or WebSocket:

   [mcp.github]
   url = "https://api.githubcopilot.com/mcp/"
   headers = { Authorization = "Bearer ${GITHUB_TOKEN}" }
   enabled = false   # flip to true when GITHUB_TOKEN is set

Configure by asking

1. Switch the model for this session.

   › switch to lora/smart
   ● malac_settings use_model=lora/smart
     ⎿ This session switches to lora/smart from the next message.
   

   malac_settings only looks and switches the session's model; it never asks.

2. Change a setting.

   › allow python3 -m unittest without asking, in my user config
   ? malac_configure user config: permissions.allow = ["notes__*","bash(python3 -m unittest*)"]
     [y] allow  [a] always  [n] deny  allowed
   ● malac_configure user config: permissions.allow = ["notes__*","bash(python3 -m unittest*)"]
     ⎿ Saved /Users/you/.malac/config.toml. New sessions use it; running sessions keep their settings until restarted (the web UI can apply them right away).
   

   The prompt shows exactly which key changes and how. The edit keeps your file's comments and layout, and the result is validated before it is saved.

3. Try a few more.

   › let me open the web UI from my laptop on the LAN
   › set the context window of lora/smart to 200k
   › is there a newer malac?
   

   These map to web.remote = true (applied when the daemon restarts), models."lora/smart".context_window = 200000, and malac_settings with show: "status".

4. Check the result.

   malac config show

To skip the prompt for safe changes, pre-approve them with a rule on action:key, for example malac_configure(set:ui.*). See Configure malac by asking.

What you learned

• Agent types are Markdown files with a role, tools and an optional model; the agent delegates to them by name.
• Skills are instructions the agent reads when a task matches; AGENTS.md holds rules for every task.
• MCP servers add tools under a <server>__ prefix and follow the same permission rules.
• malac can inspect and change its own configuration, and asks before it writes.

Next, tutorial 7 moves the agents to a server. To share agent types, skills and commands with a team, bundle them as a plugin. The reference has every flag, command and setting.