Skip to main content
0 reactions

Rasa Tutorial — Part 3: Write a Skill’s Instructions

Featured card for Rasa Tutorial Part 3, Write a Skill’s Instructions: a skill.md file with the frontmatter name Branch Hours and a description line, followed by lines of instructions, and the JD Bots logo.
Rasa Tutorial, Part 3: Write a Skill’s Instructions.

In Rasa’s Mantle engine, everything your agent can do is a skill, and every skill starts as instructions written in plain language. In this part of the Rasa Tutorial, you write your first skill’s instructions: a new skill that tells customers when the bank’s branches are open. There’s no code, just one file.

By the end, the banking agent from Part 2 will have a second skill, branch_hours. You’ll see in the Rasa Inspector how the agent picked it and followed its instructions.

This is Part 3 of the Rasa Tutorial. The parts in Module B, Building Skills:

  • Part 3: Write a Skill’s Instructions (you are here)
  • Part 4: Tools: Let Your Agent Run Python
  • Part 5: Memory: Remember What Matters
  • Part 6: References: Answer from Your Documents
  • Part 7: Responses: Control the Exact Wording
All parts of the Rasa Tutorial

Module A: Start Here

Module B: Building Skills

Module C: Progressive Control

  • Part 8: Tool Constraints
  • Part 9: Scoped Instructions
  • Part 10: Ordered Blocks
  • Part 11: Sub-skills and Composition

Module D: Orchestration

  • Part 12: The Runtime Loop: How Mantle Handles a Turn
  • Part 13: Guarantees and Guardrails
  • Part 14: Skills and Routing
  • Part 15: Context Management

Module E: Agent Setup

  • Part 16: agent.yml: Identity, Persona and Rules
  • Part 17: integrations.yml: Claude, Model Groups and Routing
  • Part 18: MCP Tools
  • Part 19: Hooks

Module F: Testing

  • Part 20: Simulate and Evaluate Your Agent
  • Part 21: Scenarios and Assertions
  • Part 22: Build Faster with the Rasa Copilot

Module G: Voice

  • Part 23: Talk to Your Agent in the Browser
  • Part 24: Designing for Voice
  • Part 25: Connect a Phone Line
  • Part 26: Test and Monitor Voice

Module H: Channels

  • Part 27: The REST Channel and a Website Chat Widget
  • Part 28: Microsoft Teams

Module I: Observability

  • Part 29: Tracing with Langfuse
  • Part 30: Metrics and Conversation Events

Module J: Deploy

  • Part 31: Run Your Agent with Docker
  • Part 32: CI/CD for a Rasa Agent
  • Part 33: Deploy to Kubernetes with Rasa’s Helm Chart
  • Part 34: Load Testing
  • Part 35: Deploy on AWS
  • Part 36: Deploy on Azure
  • Part 37: Deploy on Google Cloud

Module K: Rasa Studio

  • Part 38: Rasa Studio with a Mantle Agent

Module L: Wrap-up

  • Part 39: Final Project, Cheat Sheet and What to Learn Next

Cost: Rasa’s Developer Edition licence is free. Claude is pay-per-use: Claude Sonnet 5.5, the model this series uses, costs $2 per million input tokens and $10 per million output tokens (Claude pricing (opens in a new tab)). In this part you send two messages. With the greeting, they make four calls to Claude, which cost about $0.03. That’s an estimate: in Part 2, eight calls cost $0.05 on the Claude Console.

Prerequisites

Step 1: Create a Folder for the Skill

Open Terminal, go to your project folder and turn on its virtual environment:

TerminalBash
cd my-rasa-agent
source .venv/bin/activate

Each skill lives in its own folder inside the skills folder. Create one for the new skill:

TerminalBash
mkdir skills/branch_hours

The folder’s name is the skill’s id, which Mantle uses to tell your skills apart. Name it like the starter’s view_transactions: lowercase words joined by underscores. Don’t start it with builtin_, because Rasa keeps that prefix for its own skills.

Step 2: Write the Skill’s Name and Description

In your text editor, create a file named skill.md in the new skills/branch_hours folder. A skill.md file has two parts: a short header between two --- lines, called the frontmatter, and the instructions below it. Start with the frontmatter:

skills/branch_hours/skill.md (excerpt)Plain text
---
name: Branch Hours
description: Branch opening hours - what time branches open and close on weekdays, weekends and public holidays
---
  • name is the skill’s display name. The Inspector shows it.
  • description says what the skill covers. When a customer writes, Mantle reads the descriptions of all your skills and picks the one that fits, so this line decides when your skill runs.

Rasa’s advice for descriptions: put the subject first (“Branch opening hours”), then what the skill does with it, and use the words your customers use, such as “weekends” and “public holidays”. Separate the two halves with a dash. A colon has a meaning in this header, so a description with a colon would need double quotes around it.

Step 3: Write the Instructions

Below the second --- line, write what the agent should do, the way you’d brief a new colleague: the facts it needs, and how to answer.

skills/branch_hours/skill.md (excerpt)Plain text
Tell the customer when our branches are open. Every branch keeps the same
hours:

- Monday to Friday: 9 am to 5 pm
- Saturday: 9 am to 1 pm
- Sunday and public holidays: closed

Answer for the day the customer asks about. If they don't name a day, give
the hours for the whole week.

When the branches are closed, mention that the mobile app works around the
clock.
  • The first sentence names the job. The list gives the facts. Use bullets for facts that don’t depend on each other, and a numbered list when steps must happen in order.
  • The last two paragraphs say how to answer: for one day or for the whole week, and what to suggest when the branches are closed. Say what you want the agent to do, and let it choose the words.

Here’s the complete file. Save it:

skills/branch_hours/skill.mdPlain text
---
name: Branch Hours
description: Branch opening hours - what time branches open and close on weekdays, weekends and public holidays
---

Tell the customer when our branches are open. Every branch keeps the same
hours:

- Monday to Friday: 9 am to 5 pm
- Saturday: 9 am to 1 pm
- Sunday and public holidays: closed

Answer for the day the customer asks about. If they don't name a day, give
the hours for the whole week.

When the branches are closed, mention that the mobile app works around the
clock.

A few facts like these belong in the instructions. Longer material, such as a full list of fees, goes in a skill’s references, which Part 6 covers.

Step 4: Train Your Agent

TerminalBash
rasa train

rasa train checks your skill files and packs them into a new model file:

Output (the lines that matter)Plain text
2026-11-19 08:31:11 INFO     rasa.mantle.model_archive.snapshot  - [info     ] Mantle model package saved at 'models/20261119-083111-plumb-planner.tar.gz'.

If skill.md has a mistake, such as a missing --- line, training stops with an error instead. The Troubleshooting table below lists the common ones.

Step 5: Ask Your Agent About Opening Hours

TerminalBash
rasa inspect

The Rasa Inspector opens in your browser. In my run, the greeting already offered branch opening hours, taken from the new description.

Type When are your branches open? and press Enter. When the reply arrives, type Are you open on Sunday?. Then click Inspect at the top of the page to see what happened behind each reply:

The Rasa Inspector in Inspect mode: the user asks when the branches are open, the event Branch Hours skill activated appears, and the agent lists the opening hours for every day; then the user asks about Sunday, and the agent says the branches are closed and the mobile app works around the clock.
Mantle picked the new Branch Hours skill, and the agent followed its instructions.
  • Branch Hours skill activated means Mantle compared your question with each skill’s description and picked the new skill.
  • The first question named no day, so the agent gave the whole week, as the instructions say. For Sunday, it said the branches are closed and mentioned the mobile app.

The middle of the page shows the active skill, with the description and instructions that Mantle loaded from your file:

The Active skill panel of the Rasa Inspector showing Branch Hours, with the skill’s description and its instructions from skill.md: the opening hours for each day, and how to answer.
The description and instructions Mantle loaded from skill.md.

Instructions are guidance: Claude follows them, but nothing forces it to. Where a mistake would be costly, Mantle lets you add rules that it enforces, which Parts 8 to 10 cover.

When you’re done, go back to Terminal and press Ctrl+C to stop the agent.

Clean Up

If the agent is still running, press Ctrl+C in Terminal to stop it. Claude charges only when your agent calls it, so a stopped agent costs nothing. Keep the my-rasa-agent folder: the next part builds on it.

Common Mistakes

MistakeDo this instead
Saving the file as rich text, or as skill.md.txtSave it as plain text, named exactly skill.md.
Writing a colon between the subject and the action in descriptionUse a dash, or put the whole description in double quotes.
Changing skill.md without training againRun rasa train, then start rasa inspect again, after every change.
Putting a long document into the instructionsKeep the instructions to the job and a few facts. Documents go in references (Part 6).

Troubleshooting

ProblemFix
Inspect mode never shows Branch Hours skill activatedCheck that the file is at skills/branch_hours/skill.md, then train again. Make the description start with its subject and use the words customers type.
Training fails with skill.markdown.invalid_frontmatter_delimiterThe file’s first line must be ---, and another --- line must close the frontmatter.
Training fails with skill.markdown.unknown_frontmatter_keyA frontmatter key is misspelled, for example descripton. Fix it and train again.

FAQ

Does a skill need Python code?

No. A skill.md with a name, a description and instructions is a complete skill. Code comes in when the agent needs to do something, such as look up data, which Part 4 covers.

Does the name field decide which skill is picked?

No. Rasa’s docs call name a display label that takes no part in choosing. Mantle picks a skill by its folder name and its description.

Will the agent always follow my instructions?

Usually, but not always, because the LLM reads them as guidance. For steps that must never go wrong, add the rules that Parts 8 to 10 cover.

Conclusion

You wrote your first skill: a folder named after it, and a skill.md whose description tells Mantle when to use the skill and whose instructions tell Claude what to say. After training, the Inspector showed the agent picking the new skill and following its instructions.

← Previous: Part 2: Create Your First Mantle Agent

Next → Part 4: Tools: Let Your Agent Run Python

Additional Resources

Rasa, Claude and other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by Rasa Technologies or Anthropic.

0 comments