Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mirobody.ai/llms.txt

Use this file to discover all available pages before exploring further.

Skills are the playbook an agent reads when a particular task is in front of it. Where a Tool is “code the agent calls”, a Skill is “prose the agent loads into context” — long-form instructions, examples, formatting rules, edge cases. The agent decides when to consult one based on its description. Mirobody supports the Claude Agent Skills format directly: any folder under skills/ that contains a SKILL.md is auto-discovered at startup and exposed to every agent that has the skill loader enabled.

​
File layout

skills/<your-skill>/
├── SKILL.md           # required — YAML frontmatter + body
├── metadata.json      # required — Mirobody discovery hints
├── LICENSE.txt        # recommended for distribution
└── ...                # any auxiliary files the playbook references
    ├── reference.md
    ├── forms.md
    └── scripts/
The whole folder is the unit. The agent reads SKILL.md end-to-end when the skill activates; anything in sibling files is referenced by relative path from the playbook.

​
SKILL.md

---
name: xlsx
description: >
  Comprehensive spreadsheet creation, editing, and analysis with support for
  formulas, formatting, data analysis, and visualization. When Claude needs to
  work with spreadsheets (.xlsx, .xlsm, .csv, .tsv, etc) for: (1) Creating new
  spreadsheets with formulas and formatting, (2) Reading or analyzing data,
  (3) Modify existing spreadsheets while preserving formulas, (4) Data analysis
  and visualization in spreadsheets, or (5) Recalculating formulas.
license: Proprietary. LICENSE.txt has complete terms
---

# Requirements for Outputs

## All Excel files

### Zero Formula Errors
- Every Excel model MUST be delivered with ZERO formula errors (#REF!, #DIV/0!, …)

### Preserve Existing Templates (when updating templates)
- Study and EXACTLY match existing format, style, and conventions when modifying files
- Never impose standardized formatting on files with established patterns

…
Frontmatter fields:
FieldRequiredPurpose
nameyesStable identifier, kebab-case. Used in logs and tool calls.
descriptionyesWhat this skill does and when to use it. The model sees this verbatim when deciding whether to load the skill. Be specific about triggers.
licenserecommendedFree-text license note.
The body is unconstrained Markdown. Write it for the model: explicit rules, worked examples, do/don’t sections, edge cases. Length is fine — the body only gets loaded into context if the agent decides this skill applies.

​
metadata.json

{
  "name": "xlsx",
  "summary": "Comprehensive spreadsheet creation, editing, and analysis …",
  "when_to_use": [
    "User uploaded an .xlsx / .csv file and asks for analysis",
    "User asks to generate a financial model from scratch"
  ],
  "when_not_to_use": [
    "User wants a one-off CSV row — use a tool directly"
  ],
  "tags": ["documents"]
}
metadata.json is Mirobody-specific. It’s lighter weight than the SKILL.md body and is what the skill loader scans first.
FieldPurpose
nameMust match the frontmatter name.
summaryOne- or two-sentence pitch. Shown in skill lists.
when_to_useArray of intent triggers. The orchestrator matches user requests against these.
when_not_to_useNegative triggers — keeps the skill from over-firing.
tagsFree-form labels for filtering.
If when_to_use / when_not_to_use are left empty, the loader falls back to matching on description from SKILL.md.

​
A complete example: the xlsx skill

The upstream repo ships four reference skills under skills/ — xlsx, pdf, pptx, docx. The xlsx skill is the most representative: 
skills/xlsx/
├── SKILL.md       # 200+ lines of formula / formatting / financial-model rules
├── metadata.json
├── recalc.py      # auxiliary script the playbook calls when needed
└── LICENSE.txt
Walk through what happens when a user uploads a spreadsheet:
  1. Agent (e.g. DeepAgent) sees an .xlsx attachment in the user message.
  2. Skill loader scans metadata.json files; xlsx’s summary matches.
  3. The full SKILL.md body is injected into the system context for this turn.
  4. The agent now has all the formatting standards, color-coding conventions, and recalc.py documentation it needs — no extra tool calls required.

​
Adding your own skill

1

Pick a slot in `skills/`

Use kebab-case for the folder name. Multi-word skills like glucose-coach or legal-citation are fine.
2

Write `SKILL.md`

Start with frontmatter (name, description, license). Then write the playbook in plain Markdown. Aim for “I’m onboarding a new colleague” tone — explicit, with worked examples.
3

Write `metadata.json`

At minimum: name, summary, and either populated when_to_use or a strong description in SKILL.md. Add tags if you want to filter skills in custom agents.
4

Restart the server

Skills are auto-discovered at startup. After ./deploy.sh (or restarting your local dev server) the skill is live across every agent that runs the skill loader.
5

Verify it fires

Ask the model something that should trigger the skill. In the chat session log you’ll see the skill name appear in the system context once it activates.

​
Skills vs Tools — quick mental model

ToolSkill
FormPython functionMarkdown playbook + metadata
When agent uses itCalls it like a function and reads the return valueLoads the whole body into context when relevant
Best forSide-effecting actions, structured data fetchesDomain rules, formats, examples, style guides
DiscoveryAuto-loaded from tools/Auto-loaded from skills/
Versioned withPinned importsThe folder itself + git
Tools answer “what can I do?”; Skills answer “how should I do it?”. Most real domains need both — for example, a health-coach skill that tells the model the tone and structure for advice, paired with fetch_health_data, search_health_indicators, and chart_* tools that supply the underlying numbers.

​
Next steps

Adding Tools

The other half: write Python functions the agent can call.

Tools & Agents Overview

See how Skills, Tools, and the three agent types fit together.