Skip to main content
MeshAgent agents such as ChatBot, Worker, TaskRunner, and MailBot support skills. In practice, you usually load them with repeated --skill-dir flags and combine them with rules and tools.

​
Rules, tools, and skills

These three layers do different jobs:
  • Rules shape the agent’s ongoing behavior.
  • Tools give the agent capabilities such as storage, shell access, or web search.
  • Skills give the agent reusable workflows for specific kinds of tasks.
That means a strong agent often uses all three:
  • rules for identity, safety, and tone
  • tools for actions and data access
  • skills for repeatable task playbooks

​
Runnable example

The example below creates a small local skill and then starts a ChatBot that can use it.

​
Step 1: Create a sample skill

bash
mkdir -p ./skills/release-summary

cat > ./skills/release-summary/SKILL.md <<'EOF'
---
name: release-summary
description: Summarize release notes, changelogs, or shipped features into a concise update for humans. Use this when the user asks for a release summary, changelog rewrite, product update, or announcement draft.
---

# Release Summary

Use this skill when the user wants a readable summary of recent changes.

## Goal

Turn raw release notes or a changelog into a short, clear summary.

## Process

1. Read the source material carefully.
2. Group related changes together.
3. Highlight user-facing impact, not just internal implementation details.
4. Keep the output concise and easy to skim.

## Output

- Start with a short overview paragraph.
- Then give 3-5 bullet points with the most important updates.
- If the source material is unclear, say what is uncertain.
EOF

​
Step 2: Start a ChatBot with the skill

bash
meshagent setup

meshagent chatbot join \
  --room quickstart \
  --agent-name chatbot \
  --require-storage \
  --room-rules "agents/chatbot/rules.txt" \
  --skill-dir ./skills/release-summary \
  --rule "You are a helpful assistant."

​
Step 3: Use the agent

Once the agent is running, ask it something like:
Summarize these release notes into a short customer-facing update.
You can paste the notes into the chat, store them in room files, or combine the skill with other tools depending on your setup.

​
Loading multiple skills

To load more than one skill, repeat --skill-dir:
bash
meshagent chatbot join \
  --room quickstart \
  --agent-name chatbot \
  --require-storage \
  --skill-dir ./skills/release-summary \
  --skill-dir ./skills/brand-review
Each --skill-dir points at one skill directory containing its own SKILL.md.

​
Important behavior notes

  • Skills are guidance, not callable tools or functions.
  • The model decides whether a skill is relevant for the current task.
  • Skills do not automatically grant capabilities.
  • If a skill expects storage, shell access, web search, or another toolkit, you still need to enable those tools for the agent.
This is the core distinction from function calling or tools: a tool performs an action, while a skill helps the agent decide how to approach the task.

​
Troubleshooting

​
The agent is not using the skill

Check:
  • the description clearly states when the skill should trigger
  • the task actually matches that description
  • the --skill-dir path points at the folder that contains SKILL.md

​
The skill triggers at the wrong times

The description is usually too broad or too vague. Tighten the trigger language and name the specific task types it should handle.

​
The skill expects capabilities the agent does not have

Add the required tools or revise the skill so it matches the runtime environment.

​
The skill is too large or unfocused

Split the workflow into smaller skills, and move large supporting content into references/ or assets/.

​
Where to go next