Skills

Skills are markdown files that describe named capabilities. When loaded onto an agent, they are injected into the system prompt, nudging the model to apply them when relevant — without any extra prompt engineering from you.

---

Skill file format

A skill file is a markdown file with YAML-style frontmatter:

---
name: concise-replies
description: Use this skill to keep all responses short and to the point.
---

Reply in plain language. Avoid bullet points unless the user asks for a list.
Never repeat the user's question back to them. Keep answers under three sentences.

Section	Purpose
name	Short identifier. Injected into the system prompt.
description	When to apply the skill. The model reads this to decide relevance.
Body	Detailed instructions the model follows when the skill is active.

---

Loading skills

class MyAgent(Agent):
    def __init__(self):
        self.system_description = "You are a helpful assistant."
        self.set_model("openai", "gpt-4.1-mini")
        self.load_system_skill("skills/concise.md")          # one skill
        self.load_system_skills([                             # several at once
            "skills/concise.md",
            "skills/formal-tone.md",
        ])
        super().__init__()

Important

Load skills before super().__init__(). The system prompt is assembled during __init__.

---

What gets injected

When skills are loaded, the system prompt gains an Available skills block:

You are a helpful assistant.

Available skills:

Skill: concise-replies
Description: Use this skill to keep all responses short and to the point.

Skill: formal-tone
Description: Use this skill when communicating in a professional or academic context.

The model uses the description field to decide when to apply each skill.

---

Example: shaping response format

This example shows the difference a skill makes. Both agents get the same question; only one has the skill.

Skill file — skills/step_by_step.md:

---
name: step-by-step
description: Use this skill when explaining how something works or how to do a task.
---

Always structure your explanation as clearly numbered steps.
Start each step with a bold action verb (e.g. **Open**, **Run**, **Check**).
After the steps, add a one-line summary prefixed with "Summary:".
Never use prose paragraphs — only numbered steps and the summary line.

Agent without skill:

How do I make a cup of tea?

Boil some water, add a tea bag to a mug, pour the water over it, wait a few minutes,
then remove the bag and add milk or sugar if you like.

Agent with skill:

How do I make a cup of tea?

1. **Boil** a full kettle of water.
2. **Place** a tea bag in a clean mug.
3. **Pour** the boiled water over the tea bag.
4. **Steep** for 3–5 minutes depending on strength preference.
5. **Remove** the tea bag and add milk or sugar to taste.

Summary: Boil water, steep a tea bag for 3–5 minutes, then season to taste.

---

Accessing skill data

The loaded skills are available as a list on the agent:

agent = MyAgent()
print(agent.skills)
# [{"name": "concise-replies", "description": "...", "content": "..."}]

Key	Value
name	From frontmatter
description	From frontmatter
content	The body of the markdown file

---

Tips for writing good skills

• Be specific in the description. The model uses it to decide when to apply the skill. Vague descriptions lead to inconsistent behaviour.
• Keep the body actionable. Use instructions like "Always do X" or "Never do Y", not general advice.
• One skill, one concern. A skill for tone and a skill for formatting are better than one skill trying to do both.

---

Next

Multi-agent orchestration →