A skill is instructions in plain English, saved as a SKILL.md file in a folder of its own in your vault’s Skills/ folder. You can write one in the app’s editor or in any text editor, and the two are the same file. This page covers both, then what a skill can do and how to make one that works every time. For running skills and the built-in ones, see Skills.

Make a skill in the app

On the Skills page, press New Skill, or the New skill card after your skills. A profile’s Add a step menu has New skill… too. The editor has four parts:

The name, across the top (Name your skill). Type it as you would say it, such as “Client recap”. It is saved as the folder name client-recap: lowercase letters, digits and hyphens, at most 64 characters. The line under the name shows where the file is, such as Skills/client-recap/SKILL.md.
INSTRUCTIONS: the steps, in plain English. It is the same editor notes use: type / for headings, lists and more, and switch between Live Preview and Source with the toggle beside the label.
DESCRIPTION: what the skill does, and when to use it. The assistant reads it to decide when the skill fits a question, so it is required.
WORKS ON: what the skill runs on.
- Meetings: a meeting’s transcript, notes and documents, recorded or not.
- Calendar events: a meeting on your calendar, usually one coming up, with its time, people and invite.
- Notes: a note in your vault, such as a weekly to-do list: its text, and changing it.
- Also without one: optional, so it can run with none of them.
The box under them says what that means: what Run on… offers, and which automations suit the skill. A new skill starts on Meetings and Also without one.

Press Create Skill (Save for a skill you are changing). Closing with unsaved changes asks first.

Renaming a skill renames its folder, with every file in it. Automations and profile steps that run the skill still look for the old name: an automation’s card then says Will not run:, and the profile step says the skill is not in your Skills folder. Edit them to pick the new name.

You can also ask the assistant to write a skill for you. It proposes the new skill as a change, which always waits for you to keep or discard, whatever the assistant’s mode.

The SKILL.md file

A skill is a folder whose name is the skill’s name:

Skills/
└── client-recap/
    ├── SKILL.md       required
    └── examples/      optional: anything the instructions point to

SKILL.md is in the open Agent Skills format: a header between --- lines, then the instructions in Markdown.

---
name: client-recap
description: Writes a short recap of a client call. Use it after a call with a client.
metadata:
  accepts: "meeting"
  document: "Client recap"
---
Write a recap of this client call.

1. …

The header

name: the same as the folder’s name. Lowercase letters, digits and single hyphens, at most 64 characters.
description: what it does, then when to use it, in one or two sentences. The skill’s card shows the first sentence.
metadata: the settings Samurai Scribe reads, below. Write metadata: on a line of its own, then one level of key: "value" lines, indented, with each value in quotes.

Other keys, such as license, and other metadata keys are kept exactly as written.

The settings under metadata

Key	What it does
`accepts`	What the skill runs on: `meeting`, `calendar_event`, `note` or `none`, comma-separated, in the order Run on… offers them. `none` beside another word makes that one optional: `"meeting, none"` runs on a meeting or on nothing. The editor’s WORKS ON sets it. Without it, the app guesses: a meeting if the skill has a `document` or suggests `after_meeting`, otherwise nothing.
`document`	When the skill runs as a step of a processing profile, the name of the document its reply is saved as, such as `"Summary"`. Without it, the document is named after the skill, such as “Client recap”. It never writes over a document of yours: if you have one of that name, the skill’s goes beside it as “Client recap 2”. The editor doesn’t show this setting; a save keeps it.
`suggested_trigger`	When you suggest running it. It only fills in a new automation for whoever installs the skill; nothing runs because of it. `after_meeting`; `before_meeting`, or `before_meeting 15` for 15 minutes before; or `schedule` and a time: `schedule daily 08:00`, `schedule weekdays 08:00`, `schedule monday 09:00` or `schedule hourly`, in local time. Change it in the file: the editor keeps it as it is.
`requires`	The connections the skill needs, comma-separated, by the ids the shared library uses: `linear`, `atlassian` (Jira & Confluence), `notion`, `todoist`, `monday`, `clickup`, `attio`. An automation doesn’t run the skill until each one is connected.
`argument-hint`	What a run takes besides what it runs on, such as `"[language]"`. The skill then gets a field wherever it runs, labelled from the hint (“Language”). See Arguments. The editor doesn’t show it; a save keeps it.
`tools`	The tools it uses, comma-separated: the app’s own by name (`"digest_transcript, write_document"`), and a connection’s actions as `<connection>__<action>` (`"linear__list_teams, linear__save_issue"`). A skill that lists any of the app’s own tools is offered only those, wherever it runs; one that lists none is offered all of them. Of a connection, a run is offered only the actions listed, not the service’s others, and each must belong to a connection in `requires`.
`category`	A short label the shared library groups skills by: `Preparation`, `Follow-up`, `Review`, `Sales`, `Learning`.
`tested_with`	`local`, `cloud` or `local, cloud`: the kinds of model the author checked it on. The library shows Tested on the built-in model for `local`.
`version`, `spec`	Your own version of the skill, and the version of the format it was written for (`"1"`).

The instructions

Everything after the header is the instructions: the steps the skill follows, in Markdown. A skill with no instructions can’t run. Writing instructions that work has tips.

Other files

Files beside SKILL.md, such as examples or reference notes, are material the instructions can point to, and they travel with the skill when it is shared. A skill reads one with read_note and its path in the vault, such as Skills/client-recap/examples/good-recap.md.

Arguments

A skill can take something besides what it runs on: a language, an audience, a tone. It works as in Claude Code’s skills. Give the skill an argument-hint under metadata, and write $ARGUMENTS in its instructions where the value goes:

---
name: brief-for
description: Writes a short brief of a meeting for one audience. Use it when someone asks for a meeting summed up for a particular group.
metadata:
  accepts: "meeting"
  argument-hint: "[audience]"
---
Write a short brief of this meeting for this audience: $ARGUMENTS

1. If no audience is given above, ask the user who the brief is for, and stop.
2. …

What the run is given replaces $ARGUMENTS. It is given the same way wherever the skill runs:

In a chat, as the text you type after its name: /brief-for the sales team. The list of skills after / shows the hint beside the name, such as /brief-for [audience].
From the Skills page, in a field named after the hint (Audience) that opens when you press ▶. It starts on what you gave last time.
As a step of a processing profile, in the same field on the step’s card, given every time the step runs.
From an automation, in the same field in the automation’s editor (“What the skill is given each time it runs.”).
When the assistant follows the skill itself, it fills the value in from your request.

Some rules:

With nothing given, $ARGUMENTS is left empty, so say what to do then, as step 1 above does.
Instructions without $ARGUMENTS get what was given at the end, as “For this run: …”.
Only $ARGUMENTS is replaced. Claude Code’s $0, $1 and named arguments are not.
The value is free text: there are no types or lists of choices.

The built-in Translate transcript skill works this way: its hint is [language], so the transcript’s ⋮ → Translate transcript… asks for a language, and /translate-transcript German in a chat does the same.

What a skill can do

A skill acts through tools. Name the tools in the instructions: a model follows “read the Summary with read_document” far better than “look at the summary”. A skill does the same things wherever it runs; where it runs only changes a few tools:

App: the assistant, including skills you run from the Skills page and automations.
AI apps: Claude Desktop, Claude Code, Codex, Cursor or Gemini CLI, connected in Settings → AI Apps.
Steps: the skill as a step of a processing profile.

Anywhere, a skill can also follow another of your skills, or propose a new one. A skill meant for AI apps as well as the app should read meetings with read_transcript: AI apps don’t have digest_transcript.

A skill may change notes anywhere in the vault that AI may edit (Settings → AI Apps → Folder Access). Who approves a change is your choice, never the skill’s:

In a chat, or run from the Skills page: the assistant’s mode.
As a profile step: the step’s two settings, This meeting and Elsewhere. See Processing profiles.
From an automation: the same two settings, in the automation’s editor. See Automations.

Moves and deletes outside a meeting always wait for you, and so does any change to your Skills, Scripts and Dictionary folders.

As a profile step, a skill’s reply is saved as the document named by document, and it may write at most 8 documents in one run with write_document. It can’t write a document called Transcript or Notes, which are the meeting’s own; it changes the transcript with edit_transcript, rewrite_transcript or translate_transcript instead. A step that changes the transcript or notes and writes no document ends with a sentence or two on what it changed, kept with that change rather than saved as a document.

A skill that works on one note says accepts: "note". Run from the Skills page it asks which note; in a chat it takes the note you attached with @, or the one open. Name a note by its path in the vault, with no leading slash, such as Weekly/W1_log.md. Read it with read_note first, then change it with edit_note.

Tools that read

Tool	What it does	Where
`search`	Searches transcripts, meeting notes, titles, speakers and your other notes, or one meeting.	App · AI apps · Steps
`list_meetings`	Meetings by date or title, newest first.	App · AI apps · Steps
`upcoming_meetings`	Calendar meetings in the next two days, with who is invited.	App · AI apps · Steps
`get_meeting`	One meeting: its title, date, speakers, notes and folder, and its invite’s attendees with their addresses, you marked `(you)`.	App · AI apps · Steps
`read_transcript`	A meeting’s transcript, a stretch at a time.	App · AI apps · Steps
`digest_transcript`	Reads a whole meeting for one instruction and returns the notes. The way to read a long meeting on a small model.	App · Steps
`speaker_stats`	How the talking was shared: each speaker’s share, turns, longest stretch, pace and questions, and which speaker is you.	App · AI apps · Steps
`read_document`	One of a meeting’s documents by name, such as `Summary` or `Notes`, or a file attached to it.	App · AI apps · Steps
`list_folder`	What a folder in the vault holds.	App · AI apps · Steps
`read_note`	Any note by its path in the vault. PDFs, Word files and PowerPoint decks are read as text, without their pictures.	App · AI apps · Steps
`list_notebooks`	Your notebooks and the meetings in each.	App · AI apps · Steps
`read_memory`	What you asked the assistant to remember about you.	App · AI apps · Steps
`list_skills`	Your skills.	App · AI apps · Steps

Tools that propose changes

Each change is one you keep or discard, unless the mode or the setting where it runs lets it apply by itself, with undo.

Tool	What it does	Where
`create_note`, `edit_note`	A new note, or changes to one.	App · AI apps · Steps*
`move_note`, `delete_note`	Moving a note, or moving it to the trash. Outside a meeting they wait for you unless the assistant’s mode is Auto; from an AI app, a step or an automation they always wait.	App · AI apps · Steps*
`create_notebook`, `add_to_notebook`	A new notebook, or meetings added to one.	App · AI apps · Steps*
`edit_transcript`	Corrections to a transcript: a word fixed everywhere, a line moved to another speaker, a speaker named, lines split or merged.	App · AI apps · Steps
`rewrite_transcript`	One correction run over a whole transcript, however long, as one change. It can also remove lines you asked to have removed.	App · Steps
`translate_transcript`	A whole transcript in another language, as one change. Every line keeps its time and speaker.	App · Steps
`rename_person`	A person renamed in every meeting they speak in.	App · AI apps · Steps*
`remember`, `edit_memory`	A line added to what the assistant remembers about you, or changes to it.	App
`check_change`	Whether a change it proposed was kept.	App · AI apps

* A step is offered these unless its Elsewhere setting is Ask: they change something outside the meeting.

Other tools

Tool	What it does	Where
`draft_email`	Offers an email draft (to, subject, body) that you open in your mail app or Gmail. Nothing is sent. A draft still holding a `[placeholder]`, or addressed to you, is refused.	App
`write_document`	Writes a document into the meeting being processed.	Steps
`set_title`	Names the meeting being processed, unless you named it yourself or it is linked to a calendar event.	Steps

Connections in a skill

A skill that works in a service lists the connection in requires and the actions it uses in tools, and its instructions name those actions:

---
name: action-items-to-linear
description: Files a meeting's action items in Linear, one issue per task. Use it after a meeting whose tasks your team tracks in Linear.
metadata:
  accepts: "meeting"
  requires: "linear"
  tools: "linear__list_teams, linear__save_issue"
---
1. Read the meeting's Summary with read_document and find its action items.
2. Find the team with linear__list_teams.
3. For each action item, create an issue with linear__save_issue.
…

What each action may do is yours to decide, on the Connections tab of the Skills page: Off, Ask, Allow or Allow in automatic runs. A skill can’t change that. In a run nobody is watching, an action that changes something waits for your approval unless you chose Allow in automatic runs; see Automations.

Writing instructions that work

The built-in model is small, and a skill also runs on whatever model you choose. These habits make a skill reliable on all of them:

Short, numbered steps. One action each, naming the tool to use.
Say what the output looks like: its sections in order, the form of a line, roughly how long.
Say what to do when the material isn’t there. “If the meeting has no transcript yet, say so in one line and stop.” A meeting can have notes, documents or a calendar invite and still no transcript.
Use only what was said. Tell it not to invent names, dates or numbers. A skill that makes up a decision is worse than none.
For long meetings, read with digest_transcript rather than paging through read_transcript.
Name the language. “Write in the same language as the meeting.”
For a profile step, the reply is the document. Tell it to begin with the first heading, with no title or preamble.
Say what not to touch. “Do not change anything else in the transcript.”
Keep it portable if you will share it: no folder names, people or clients of your own. Let the tools find things.
When it runs is not in the skill. That is an automation, which belongs to whoever uses the skill. suggested_trigger is only a hint.

An example

A complete skill that writes a recap of a client call:

---
name: client-recap
description: Writes a short recap of a client call — what the client asked for, what was agreed and who does what next. Use it after a call with a client.
metadata:
  accepts: "meeting"
  document: "Client recap"
  category: "Follow-up"
---
Write a recap of this client call.

1. If the meeting has no transcript yet, say so in one line and stop.
2. Read the whole meeting with digest_transcript. Ask it for: what the client asked for or worried about; anything both sides agreed; and each next step, with who owns it and any date that was said.
3. Reply with the recap itself, in Markdown, beginning with the first heading. Use these sections, and leave out any that would be empty:

## What they asked for
Short bullet points, in the client's own terms.

## What was agreed
Each agreement, stated plainly.

## Next steps
One line each: `- [ ] **Owner** — step`. Add a date only if one was said.

Rules:
- Use only what was said. Never invent a name, a date or a number.
- Call people by name when the name is known.
- Write in the same language as the meeting.

Run it from the Skills page on a few meetings to try it. Then add it as a step of a processing profile, and every meeting that profile processes gets a Client recap document. As a profile step it is free, and it writes into the meeting directly; an automation suits work outside the meeting, such as a running log or issues in a tracker.

Test and fix a skill

Run it by hand from the Skills page on at least three meetings: a short one, a long one, and one where the material it looks for isn’t there.
Read what it did. The run’s conversation shows each step and the answer. The Log tab on the Skills page keeps every run.
Fix the instructions where it went wrong, and run it again. Most problems are a step that is vague, or a missing “if there is none, stop”.

A card or the editor that says Needs fixing: names a problem with the file:

its name says ”…” but its folder is ”…”: make the name match the folder’s name.
it has no description saying what it does and when to use it: add a description.
it has no instructions: write the steps after the header.
its metadata is written in a form the app cannot edit: write metadata as one level of key: "value" lines, without nesting, lists or {…}.
its suggested_trigger cannot be read: use one of the forms in the table above.
its tools list names …, which is neither an app tool nor a tool of a connection it requires: fix the tool’s name, add its connection to requires, or remove it.

You can still run a skill that needs fixing by hand, as long as it has instructions. No automation runs it until it is fixed.

Limits

A skill’s name: at most 64 characters.
A profile step: at most 8 documents written in one run.
A skill in the shared library: at most 32 files, none larger than 512 KB. The app leaves a bigger one out of Shared skills.

The shared library is a public repository on GitHub, github.com/samuraiscribe/skills, under the MIT license. The Share a skill on GitHub card, at the end of Shared skills on the Skills page, opens it.

Try the skill on at least three real meetings of different lengths, until it is right every time.
Make sure it says what it works on with accepts. If you checked it on the built-in model, on short, medium and long meetings, add tested_with: "local".
Copy its folder from your vault’s Skills/ into the repository’s skills/ folder, and open a pull request.

The pull request is checked automatically, and a maintainer reads every skill before it is published. The repository’s CONTRIBUTING file has the details. Once it is merged, the skill appears under Shared skills for everyone.

Skills from other apps

A skill written for another app in the Agent Skills format can go in your vault’s Skills/ folder as it is. Copy its folder there, and it appears on the Skills page. Check three things:

The folder’s name matches its name.
metadata is one level of key: "value" lines. Other shapes are kept as written, but the skill shows Needs fixing: and no automation runs it.
The tools it names are Samurai Scribe’s, as listed on this page. Instructions written for another app’s tools won’t find them here.

A Claude Code skill’s argument-hint and $ARGUMENTS work here as they are, even with the hint at the top of the header, where Claude Code writes it. Write it under metadata in a new skill, since the Agent Skills format has no such key. An allowed-tools key is kept but not read: what a skill may change without asking is your setting, never the skill’s. List the tools a skill uses under metadata as tools instead.

Skills written for older versions of Samurai Scribe may carry trigger, schedule, minutes_before or title_contains keys. The app doesn’t act on them: make an automation instead, and leave them out of new skills.