Skills

A skill is a folder of instructions — a SKILL.md plus any scripts or reference files it uses — that teaches the model a procedure. You keep skills in a skills/ folder that Mework reads, then tick the ones each conversation gets.

Where skills live

Each skill is one folder directly inside a skills/ folder:

Level	Location	Used by
Global	`~/.mework/skills/<folder>/SKILL.md` (Windows: `%USERPROFILE%\.mework\skills\<folder>\SKILL.md`)	Every conversation
Workspace	`<workspace>/.mework/skills/<folder>/SKILL.md`	Conversations that include that workspace

The folder on disk is the skill: nothing is installed or copied, and a saved edit to SKILL.md applies from the next turn. The folder's name is the skill's identity; in on-demand mode the model asks for the skill by that name.

A conversation can select from the global skills and those of all its workspaces: the project's workspaces, then any it attached. When the conversation works in an isolated worktree of a workspace, that workspace's .mework/skills/ is still read from its own folder.
A workspace on WSL or an SSH machine works like a local one: its .mework/skills/ is read on that machine. The temporary project's scratch folder has no .mework; a conversation there gets the global skills and those of the workspaces it attached.
A selected skill serves the whole conversation, whichever workspace declared it. Its files stay in the folder where it was declared, which for a WSL or SSH workspace is on that machine.
Only direct children of skills/ count. Nested folders, symbolic links and folders without a SKILL.md are skipped.
A folder name may use any script (代码评审 works), but must not be empty, start or end with a space, or contain (, ), , or control characters.
SKILL.md must be UTF-8 and at most 256 KiB; a byte-order mark at the start is fine. A skill that breaks either rule is listed as Unavailable, with the reason in its tooltip.

Write a SKILL.md

~/.mework/skills/commit-helper/SKILL.md:

---
name: Commit helper
description: Prepare a conventional commit from the current diff
when_to_use: The user asks to commit or write a commit message
---
1. Run `git status` and `git diff --staged`.
2. Write a conventional commit message and check it with `scripts/check-message.sh`.

The block between the two --- lines is the frontmatter:

The first line must be ---, and a later --- line closes the block.
Each key starts at the beginning of its line, in lowercase as shown. Quotes around a value are removed.
A value goes on its key's line. description and when_to_use may also run over several lines with YAML's | or >.

Key	What it does	If it is missing
`name`	The label in the Skills list.	The first `#` heading in the body, then the folder name.
`description`	Shown in the list, and the start of the skill's trigger — the text the model reads to decide when the skill applies.	The first body line that is not empty and not a heading.
`when_to_use`	Added to the trigger: `<description> - <when_to_use>`.	The trigger is the description alone.

Every other key is ignored, including Claude Code's allowed-tools, model, disable-model-invocation and user-invocable. The trigger is cut at 1,024 characters.

The body — everything after the closing --- — is what the model receives, word for word. Paths in it are relative to the skill's folder, and the model is told where that folder is, so a skill can run its own scripts. When the conversation has more than one workspace, or its only workspace is on another machine, a workspace skill's folder is given as <path> in workspace N and a global skill's as on this computer, so the model reaches the scripts with the right workspace's tools.

Choose skills for a conversation

Open More options → Conversation settings → Skills (see Conversation settings).
Tick the skills this conversation should have.

The list refreshes by itself shortly after you add or remove a skill folder; Rescan refreshes it at once. Runs always use the files as they are on disk. The list has a Global section, then one section per workspace (see Conversation settings). The folder button on a section's heading, Open the global config folder or Open the config folder of {path}, opens that level's skills/ folder, creating it if needed. For a WSL or SSH workspace, it opens that folder on its machine in the Files pane.

Turning off a skill that the last request carried, while the model's prompt cache is still warm (30 minutes by default), is drawn orange and asks once before it applies, because it changes the system prompt. Adding a skill never warns.
Any model can gain and drop skills mid-conversation, even one that cannot take new tools.
The built-in mework preset selects no skills.

How a skill reaches the model

The Load skills on demand switch at the bottom of the Skills page decides. The built-in mework preset turns it on. Changing it while the prompt cache is warm is drawn orange.

In the prompt (off): the body of every selected skill goes into the system prompt, so the model has all of it on every request.
On demand (on): the system prompt lists only each skill's folder name and trigger. When a skill fits, the model loads its body with the skill tool. The tool appears only when at least one selected skill can be loaded, and it never asks for approval.

In on-demand mode:

A skill with no trigger text is left out of the list, so the model never learns it exists. Give every skill a description.
Two selected skills with the same folder name — one global and one in a workspace, or one in each of two workspaces — make the run fail. Rename one folder or select only one.

Skills added later

The system prompt keeps the skills the conversation started with, so the prompt cache survives. A skill you tick later arrives at that point in the conversation, as a Delivered a newly added skill card, and counts from then on as if it had been there all along. Unticking a skill removes it from the system prompt on the next turn.

Subagents get the parent conversation's skills and the same loading mode.

The Mework SDK skill

Mework SDK is built into the app and listed first in every conversation's Skills list. It teaches the model to configure Mework itself: skills, mcp.json, hooks.json, lsp.json, prompt profiles, launch.json, MEWORK.md, rules and memory, and where the in-app settings are. Tick it when you want the model to set something up for you.

It is updated with each Mework version, cannot be edited or deleted, and no preset selects it.

Delete a skill

Press the trash-can button on the row, then press it again when it reads Confirm. This deletes the whole folder, including any scripts and reference files in it.

Conversations that had the skill selected keep the selection. It shows as Dangling, and every run fails, naming it, until you untick it.

Limits

What	Limit
`SKILL.md` size	256 KiB
Trigger	1,024 characters
The skill, MCP-server and hook sections of the system prompt, together	1 MiB
Bodies of the selected skills in on-demand mode, together	1 MiB
Skills added after the conversation started, together	1 MiB

Over 1 MiB the run fails. Select fewer or smaller skills.

Troubleshooting

A skill is not in the list. Check that the folder sits directly inside skills/, is a real folder rather than a link, contains SKILL.md, and has a valid name. For a WSL or SSH workspace, the workspace's skills/ folder must be on that machine. An old .naiword/skills/ folder is still read when .mework/skills/ does not exist at that level; move it to .mework/skills/ and tick the skills again.

A row says Unavailable. Hover it for the reason — usually a file over 256 KiB or one that is not UTF-8. While a conversation has it selected, every run fails until you fix the file or untick it.

A row says Dangling. The folder was renamed, moved or deleted, so the selection matches nothing. Every run fails until you untick it; then tick the skill's new row.

The model never picks a skill loaded on demand. Check that it has a description and that the frontmatter keys start at the beginning of their lines.