Teach Muse a workflow once, keep it forever.

What a skill actually is

A skill is not a program and it grants no permissions. It is a Markdown playbook your agent reads at the moment a task matches, the same way a good runbook works for a human on-call engineer. The agent still does the work with its normal tools; the skill just decides how: the order of steps, the checks, the traps to avoid, the exact wording where wording matters.

That is why skills beat re-explaining. Anything you have corrected your agent on twice belongs in a skill: the file layout you prefer, the verification you always ask for, the step it always forgets. Write it once, and every future session starts from your procedure instead of from improvisation.

The three places skills live

• Bundled skills, shipped with Muse. Read-only, replaced whenever the app updates. You cannot install into this tier, and anything you put there would be wiped on the next update.
• Custom skills, in your agent’s home. This is the install target: ~/workspace/custom-skills/ on the agent’s own computer. Home survives machine replacements and app updates, so a skill installed here is durable.
• Libraries and catalogs you copy from. A team corpus, a shared repo, a skill someone published. Reading a skill from a library does not make it yours: it becomes active for your agent only when the folder is copied into custom skills.

Most install confusion is just tier confusion. “I can see the skill in the library” and “my agent has the skill installed” are different statements, one copy apart.

Anatomy of a skill folder

One folder per skill, folder name equal to the skill’s name. Inside, SKILL.md is required; everything else is optional support.

---
name: meeting-recap
description: Use after a meeting with notes or a transcript, when the user wants the decisions, the action items with owners, and a recap message drafted. Not for live note-taking.
---

# Meeting Recap

## Inputs
- The transcript or notes the user names. If none is named, ask once which meeting.

## Steps
1. Extract decisions first: what was decided, by whom, and anything left open.
2. Extract action items: one line each, with an owner and a date if one was stated.
   Never invent an owner or a date.
3. Draft the recap in the user's voice: decisions, then actions, then open questions.
4. Show the draft. Send nothing until the user approves it.

## Checks
- Every action item traces to a line in the notes.
- Names and dates are copied exactly, never reconstructed.

Two details do the heavy lifting. The name in the frontmatter must match the folder name, or the skill is invalid. And the description is the trigger: the catalog matches tasks against it, so write it as “Use when…” with the real situations named, plus a “not for” if a neighbouring task gets misrouted.

A small skill.yaml can sit alongside it with catalog metadata (title, category, whether it is listed by default):

name: "meeting-recap"
title: "Meeting Recap"
description: "Turn meeting notes or a transcript into decisions, owned action items and an approved recap draft."
category: "Work and knowledge"
include_in_prompt: false

Longer material goes in a references/ folder inside the skill, linked from SKILL.md, so the playbook itself stays short enough to follow exactly.

Three ways to create one

1. Author it with your agent (best for your own workflows)

Do the workflow once, together, correcting as you go. Then ask the agent to freeze what just worked into a skill:

Make this a skill called <slug>. Write it into my custom skills folder as a
SKILL.md plus a skill.yaml: frontmatter name matching the folder name, a
description that starts with "Use when…", and the exact steps we just used,
including the checks. No secrets, no machine-specific absolute paths. Then
prove it works: search the skill catalog for it, read it back to me, and run
it once on a small real case.

This route captures the corrections, not just the happy path, which is exactly the part a from-scratch write-up misses.

2. Copy it from a library

If a skill already exists in a corpus or catalog you trust, install is a copy plus a portability pass:

# 1. Copy the skill folder out of the library and into your agent's
#    custom skills folder (the durable one, in its home directory):
cp -r <library>/meeting-recap ~/workspace/custom-skills/

# 2. Then ask the agent to prove the install:
#    "Search your skill catalog for meeting-recap and read it back."

Portability pass: no secrets inside the skill, no absolute paths from the author’s machine, and any bundled script or CLI actually runs on your agent’s computer.

3. Install it from a published repo

Same copy, one extra step first: your agent fetches the repo, audits the skill (frontmatter parses, name matches folder, no credential-shaped strings, paths are portable), places the folder in custom skills, and verifies any bundled tooling runs. Treat a skill from the internet like any other code you install, because its instructions will steer your agent.

Verify it like you mean it

• Search the catalog. Ask the agent to search its skills for your skill’s topic. Your skill should come back by name.
• Read it back. The agent opens the installed SKILL.md from custom skills, not from the library copy.
• Run it once. Give a small real task that matches the description and watch the steps happen in order.
• Fix the trigger, not the task. If it did not fire, the description is too narrow or too vague. Edit the installed copy, that is the authoritative one.

Checklist

1. One folder per skill; frontmatter name matches the folder name.
2. Description starts with when to use it, and names the real situations.
3. Steps and checks, not vibes: someone else could follow it cold.
4. No secrets, no machine-specific absolute paths inside the skill.
5. Installed in ~/workspace/custom-skills/, the durable home tier.
6. Verified: catalog search finds it, agent reads it back, one live run passes.
7. Later edits go to the installed copy; it is the authoritative version.

Based on a live Muse install, verified 2026-10-15: the three tiers, the SKILL.md plus skill.yaml layout, catalog discovery, and all three install routes were exercised end to end on a real agent. This guide deliberately states no skill counts: the bundled catalog changes between versions, and a number printed here would quietly go stale.