Skip to main content

​
What is a skill?

A skill is a reusable workflow or playbook that helps an agent handle a class of tasks better. MeshAgent supports the open Agent Skills format, so you can point an agent at one or more skill directories and let it discover and follow those instructions when they are relevant. Skills are useful when you want to package domain knowledge, task steps, output expectations, or review criteria in a reusable format. Skills are packaged as folders that can include instructions, scripts, and other resources that agents can leverage to perform tasks more effectively. Skills allow you to use the model’s context window more effectively by only having agents discover and read skills when they need them instead of always loading the details into the agent’s system prompt.

​
Skills vs tools, rules, and user prompts

These concepts work together, but they are not the same:
  • System prompt / Rules: the set of instructions or rules the agent sees every turn, this typically contains information about it’s persona or other information to drive consistent behavior across turns.
  • User prompt: the task-specific request for the current turn.
  • Skill: a reusable task playbook the agent can read and apply when needed.
  • Tool: a callable capability such as web search, shell access, storage access, or another app action.
The key distinction is:
  • Tools do work
  • Skills explain how to do work
In practice, a skill often tells the agent which tools to use, which files or references to inspect, what sequence to follow, and what output shape to produce.

​
The common Agent Skills format

MeshAgent skills follow the common Agent Skills pattern used by several agent runtimes:
  1. A skill lives in its own directory.
  2. The directory contains a SKILL.md file.
  3. SKILL.md starts with a small YAML metadata block such as name and description, followed by the skill instructions written in normal Markdown.
  4. The directory may also include helper resources such as references/, scripts/, assets/, templates, example files, or other supporting content.
A minimal skill looks like this: 
my-skill/
├── SKILL.md
└── references/
    └── examples.md

​
How MeshAgent supports skills

MeshAgent agents accept skills through repeated --skill-dir flags in the CLI, or through skill_dirs in the corresponding Python implementations. When you provide skill directories:
  1. MeshAgent reads the skill metadata and instructions.
  2. The skills are surfaced into the agent’s rules/context.
  3. The model decides when a skill is relevant.
  4. The agent carries out the workflow using the tools and room access you have enabled.
This is different from tool or function calling. A skill is not itself a callable tool. Instead, it helps the model decide how to handle a task, and the agent then uses whatever tools are available to do the work.

​
Which MeshAgent agents support skills?

MeshAgent agents including ChatBot, Worker, TaskRunner, and MailBot support this pattern. If a MeshAgent CLI runtime exposes --skill-dir, the same mental model applies: skills provide reusable guidance, while tools provide the executable capabilities.

​
When to use skills

Use skills when you want to:
  • Package a repeatable workflow once and reuse it across many runs.
  • Keep complex task instructions out of long inline --rule strings.
  • Teach an agent how to choose tools, inspect files, and structure its final output.
  • Ship domain-specific know-how with a deployed service.
Good examples include:
  • brand or editorial review workflows
  • code generation or refactoring playbooks
  • document transformation and reporting procedures
  • research, analysis, or QA workflows

​
When not to use skills

Do not use skills as a replacement for:
  • tools, when you need the agent to actually gain a new capability
  • rules, when the instruction should always apply to every turn
  • schemas, when the system needs strict structured inputs or outputs
If the task requires new abilities, add tools first. If the task requires better judgment about how to use existing abilities, add a skill.

​
How skills fit with rules

Use both when it helps:
  • Put ongoing system behavior in --rule or --room-rules.
  • Put reusable task playbooks in skills.
  • Let the user prompt describe the current task.
For example, a chatbot might have always-on rules about tone and safety, while a skill teaches it how to run a brand review using storage and web search tools.

​
Where to go next