Agent Skills

A skill teaches an agent a procedure without writing code. It is a directory holding one Markdown file: YAML frontmatter says what the skill is for, and the body says how to do it.

Mirobody supports Agent Skills through deepagents’ native SkillsMiddleware — the same machinery LangChain’s own deep agents use, not a bespoke loader.

Skills and tools

A tool

code the model can run

A skill

instructions the model can read

A tool extends what the agent can do. A skill changes how it does it — which order to work in, what to check against, what never to say. Nothing executes: the model reads the procedure and follows it, using the tools it already has.

Skill loading

1. 1
   SKILL_DIRS lists candidate directories the shipped default is mirobody/agent/skills; add your own and list it first
2. 2
   The first entry that exists is mounted read-only at /skills/ in DeepAgent's virtual filesystem
3. 3
   Each subdirectory holding a SKILL.md is a skill no registration, no manifest, no restart hook beyond the restart itself
4. 4
   SkillsMiddleware injects every skill's frontmatter into the prompt so the agent knows at all times what is available
5. 5
   The body is read only when a task calls for it through the /skills/ mount, with the agent's own read_file

config.{env}.yaml

SKILL_DIRS:
  - skills             # yours, checked first
  - mirobody/agent/skills

Caution

The /skills/ mount is write-denied. An agent must never edit its own skills, so write_file and edit_file are refused on that path even though they work everywhere else in the filesystem.

Note

Skills belong to DeepAgent. SkillsMiddleware is skipped for anonymous sessions — those get an in-memory filesystem with no /skills/ mount to read from — and BaseAgent has no filesystem at all, so a skill has no effect there. See Agent Types.

The required file

A skill is a directory with a SKILL.md. Nothing else is required — no manifest, no JSON sidecar, no scripts.

mirobody/agent/skills/

lab-report-walkthrough/ the directory name is the skill name

SKILL.md frontmatter (name, description) plus the instructions

SKILL.md

YAML frontmatter, then Markdown. Two keys carry the contract:

Key	Required	What it does
name	yes	The skill’s identity, matching the directory name.
description	yes	The routing decision. This is the part injected into every prompt, so it must say both what the skill does and when to use it.
license, metadata	no	Free-form; carried along, not interpreted.

SKILL.md

---
name: lab-report-walkthrough
description: Walk a person through their lab report — read the original document, organize
  results by panel, flag out-of-range values against the printed reference ranges, compare
  with their history, and explain in plain language. Use when the user uploads a lab report
  (PDF/image) or asks what their blood test results mean.
license: Apache-2.0
metadata:
  author: thetahealth
---

# Lab Report Walkthrough

Turn a raw lab report into an explanation a person can act on, without ever
drifting into diagnosis.

## Workflow

1. **Read the original, not a summary.** …

Tip

Write the description for a reader deciding whether to open the document — because that is literally the decision it drives. “Lab reports” is not enough; “Use when the user uploads a lab report (PDF/image) or asks what their blood test results mean” is.

Progressive disclosure

This is why skills scale where a bigger system prompt does not:

At startup every skill's frontmatter a line or two each — minimal standing context

When a task matches the full SKILL.md body read through /skills/

Ten skills cost ten descriptions of standing context, not ten procedures. The agent pays for the body only when it decides the skill applies.

The packaged skill

One skill ships, and it is meant to be read as the reference shape for your own:

Skill	What it encodes
lab-report-walkthrough	Read the original document rather than an extraction; organize by clinical panel rather than document order; flag against the printed reference range rather than a remembered one; compare with history when it exists; explain in plain language; never drift into diagnosis.

Three of those steps are worth stealing verbatim for any health skill. Ranges differ by lab, method, age and sex, so the range on the page beats any range the model remembers. A single value is a dot and two are a direction, so history is worth checking before saying anything. And a walkthrough sorted out-of-range first, normals summarized in one line, is the difference between a useful answer and fifteen paragraphs of “this is fine”.

Note

A skill requires only a SKILL.md file: no manifest, and no metadata.json sidecar. The loader is deepagents’ own.

Writing your own skill

Create the directory

mkdir -p skills/medication-review

Write SKILL.md

Frontmatter with name and description, then the procedure. Number the steps; the model follows them in order.

skills/medication-review/SKILL.md

---
name: medication-review
description: Review the user's current medications for interactions and timing
  conflicts. Use when the user asks about their medications, adds a new one, or
  asks whether two things can be taken together.
---

# Medication Review

## Workflow

1. **Read what they actually take.** Call `query_health_indicators` for
   medication records before assuming anything from the conversation.
2. **Group by mechanism, not by name.** Two brand names may be the same drug.
3. **Name interactions as possibilities, not verdicts.** Say what to ask a
   pharmacist, and never tell someone to stop a prescribed medication.

Point SKILL_DIRS at it and restart

config.{env}.yaml

SKILL_DIRS:
  - skills
  - mirobody/agent/skills

Only the first existing directory is mounted, so list yours ahead of the packaged one — and if you want both, keep your own skills alongside a copy of the packaged skill in the same directory.

Check it landed

Ask the agent what skills it has. The frontmatter is in its prompt, so it can answer without reading anything.

Limits of a skill

• It cannot run code. A procedure that needs computation has to call a tool — see Adding Custom Tools.
• It cannot grant access. A skill that tells the agent to read data the caller has no right to still fails at the tool boundary, where identity is enforced.
• It cannot restrict tools. Tool visibility is ALLOWED_TOOLS_* / DISALLOWED_TOOLS_* in config, not something a skill can narrow.

Next steps

Adding Custom Tools

When the procedure needs code, not instructions

→

Agent Types

The middleware stack that serves skills, and which agent has it

→

Built-in Tools

What a skill has to work with

→

Configuration

SKILL_DIRS and the rest of the directory keys

→