Writing your own skills

A skill is a written procedure a bot can follow: how you write a weekly report, how you qualify a lead, how you review a contract. It's plain text. A skill doesn't connect an app or add a tool; it tells the bot how to use what it already has.

For finding, adding and switching skills on, see Skills, Skill Guard and /learn. This page is about writing one yourself.

The format#

Murage uses the open Agent Skills format. A skill is a folder named after the skill, holding a file called SKILL.md. The file starts with a short block of settings (frontmatter) between two --- lines, followed by the instructions in Markdown.

---
name: weekly-client-report
description: |
  Writes the Friday client status report from this week's notes and tasks.
  Use when asked for a client update, weekly report or status email.
  Do NOT use for invoices or internal team updates.
---
# Weekly client report

## When to use
- The owner asks for this week's client update.

## Steps
1. Read this week's notes in the client's project folder.
2. List what shipped, what's in progress and what's blocked.
3. Keep it under 250 words, in plain language.
4. End with the one decision the client needs to make, if any.

## Don't
- Promise dates the owner hasn't confirmed.
- Send it. Save it as a draft for the owner to review.

The two fields that matter#

Murage needs two fields in the frontmatter:

• name: lowercase letters and numbers with single hyphens, such as weekly-client-report. Up to 64 characters. The folder name must match it exactly.
• description: what the skill does and when to use it, up to 1,024 characters.

The description does more work than you might expect. A bot doesn't read every skill in full on every turn. It sees a short index, one line per skill made from the name and description, and opens the full skill when the description matches the job. Up to 15 skills fit in that index. So:

• Say what the skill produces, in one sentence.
• List the words people actually use when they want it ("client update", "status email").
• Say when not to use it, if another skill is close.

Skills in Murage's library also carry optional fields such as license and a metadata block (author, version, tags, category). Murage doesn't need them for your own skills, but they're harmless and useful if you share the skill.

Size and scope#

• A SKILL.md can be up to 256 KB, but short is better. Aim for a page or two.
• In this release Murage uses the SKILL.md file only. Scripts, reference files and other files in the folder are skipped, and the review screen names each file it left out. Put everything the bot needs into SKILL.md.
• One job per skill. Two small skills beat one skill that tries to cover a whole department.

Writing tips that work

• Write steps, not essays. Numbered steps are easier for a bot to follow and for you to check.
• Say what "done" looks like. Word count, format, where to save it, who it's for.
• Name the stop points. "Save as a draft" or "ask before sending" in a skill backs up your approvals and House Rules.
• Don't paste secrets. Never put a password, API key or card number in a skill. Skill Guard looks for them and will flag or block the skill.
• Don't tell the bot to ignore its rules. Phrases like "ignore previous instructions" or "don't ask for permission" read exactly like an attack, and Skill Guard treats them that way.

Where skills live

Skills are added per bot. When a skill is added to a bot, its files sit in that bot's working folder under skills/, where the bot's engine can open them. Whether a skill is switched on for that bot is recorded separately by Murage, so editing a file in the folder can't switch a skill on by itself.

Library skills ship inside the app. Your own skills, imported skills and learned skills show in Settings → Skills under Your skills.

How Skill Guard checks a skill

Skill Guard scans a skill when you import it, install it, switch it on or edit it, and again every time Murage starts. It works offline, with no AI model, by matching the skill's text, description and trigger words against known risky patterns. It looks for things like:

• reading passwords, keys or tokens, or the settings file where they're kept;
• text that looks like a real password or key;
• sending data to an outside website;
• running risky commands or changing files outside its own folder;
• telling the bot to ignore its instructions, reveal its private instructions or act without asking;
• hidden content: encoded text, invisible characters, characters that reorder text, or text hidden far down the page;
• search words that don't match what the skill really does;
• trying to plant false memories or pressuring the bot not to say no.

Each finding has a severity and a confidence. Weak matches aren't reported at all. The result is one of three verdicts:

• Clean (shown as No red flags): nothing matched. That means no known red flags, not a guarantee.
• Needs a look: something matched that deserves a read. The skill only switches on after you choose Use it anyway.
• Blocked: a critical finding, or a serious finding from Murage's own rules. It can't be switched on, and it's switched off if it was on.

Every finding shows a plain-words message, a short quote of the matching text and the file it came from, so you can decide quickly. If your own skill is flagged, rewrite the flagged line rather than choosing Use it anyway out of habit.

Install your skill

1. Open Settings → Skills and choose Import skill.
2. Choose a SKILL.md file or a zip, or paste a link to a skill on GitHub.
3. Read the preview and Skill Guard's result.
4. Open Bot settings → Skills on the bot that should use it, choose Add a skill, and Enable it.

An imported skill lands switched off, for every bot, until you choose. Murage records where it came from and a fingerprint of its contents at import.

You can also let a bot write the first draft: switch on Settings → Experimental → Teach a skill and type /learn followed by what to learn. The draft lands switched off, and you read it before you choose Enable. See Skills, Skill Guard and /learn.

Edit and improve

Open the skill in Settings → Skills to edit it in the built-in editor, or Duplicate it and change the copy. Every edit is scanned again. Test a change on one bot before you add it to the rest of the team.

Share a skill

• With your staff: export the bots that use it. In the export, tick the skill instructions (and skill files, for a ZIP). Imported skills arrive switched off. See Share a team with your staff.
• With anyone: put the skill folder in a public GitHub repository. Others can paste the link into Import skill.
• Into Murage's own library: see Writing a skill or team for the library.

Whoever imports your skill sees Skill Guard's verdict too, so a clean, readable skill is the one people will actually switch on.