技能
技能是一个装着操作说明的文件夹：一份 SKILL.md，加上它要用到的脚本或参考文件，用来教模型按某种流程做事。把技能放进 Mework 会读取的 skills/ 文件夹，再为每个对话勾选要用的技能。
技能放在哪里
每个技能是 skills/ 文件夹下的一个直接子文件夹：
| 层级 | 位置 | 谁会用到 |
|---|---|---|
| 全局 | ~/.mework/skills/<文件夹>/SKILL.md（Windows：%USERPROFILE%\.mework\skills\<文件夹>\SKILL.md） |
所有对话 |
| 工作区 | <工作区>/.mework/skills/<文件夹>/SKILL.md |
包含这个工作区的对话 |
磁盘上的文件夹就是技能本身，不需要安装，也不会被复制；保存对 SKILL.md 的修改后，下一轮就生效。文件夹名是技能的身份，按需加载时模型就用这个名字来取技能。
- 对话可以从全局技能和它所有工作区的技能里挑选：先是项目的工作区，再是对话自己附加的工作区。对话在某个工作区的隔离工作树里工作时，这个工作区的
.mework/skills/仍从它自己的文件夹读取。 - WSL 或 SSH 机器上的工作区和本地工作区一样：它的
.mework/skills/在那台机器上读取。临时项目的临时文件夹没有.mework；那里的对话能用全局技能，以及它附加的工作区的技能。 - 选中的技能服务于整个对话，不论是哪个工作区声明的。它的文件留在声明它的文件夹里；WSL 或 SSH 工作区的技能，文件就留在那台机器上。
- 只认
skills/的直接子文件夹。嵌套的文件夹、符号链接、没有SKILL.md的文件夹都会被跳过。 - 文件夹名可以用任何文字（
代码评审没问题），但不能为空，首尾不能有空格，不能包含(、)、,或控制字符。 SKILL.md必须是 UTF-8 编码，最大 256 KiB；开头带不带字节顺序标记（BOM）都可以。不满足的技能仍会列出，但标为 不可用，原因写在悬停提示里。
编写 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`.两行 --- 之间是 frontmatter：
- 第一行必须是
---，之后再出现一行---时结束。 - 每个键都要顶格写，大小写和下表一致。值两边的引号会被去掉。
- 值写在键的同一行。
description和when_to_use也可以用 YAML 的|或>写成多行。
| 键 | 作用 | 缺省时 |
|---|---|---|
name |
技能列表里显示的名称。 | 正文里第一个 # 标题，再没有就用文件夹名。 |
description |
显示在列表里，也是技能触发说明的开头。模型靠触发说明判断什么时候该用这个技能。 | 正文里第一行既不为空、也不是标题的文字。 |
when_to_use |
接在触发说明后面：<description> - <when_to_use>。 |
触发说明只有描述。 |
其他键一律忽略，包括 Claude Code 的 allowed-tools、model、disable-model-invocation 和 user-invocable。触发说明最长 1,024 个字符，超出部分截掉。
正文是结尾那行 --- 之后的全部内容，会原样交给模型。正文里的相对路径以技能文件夹为基准，模型会被告知这个文件夹在哪里，所以技能可以运行自带的脚本。对话有多个工作区，或唯一的工作区在别的机器上时，工作区技能的文件夹会写成「工作区 N 里的 <路径>」，全局技能的文件夹则注明在本机上，模型就能用对应工作区的工具去运行脚本。
为对话选择技能
- 打开 更多选项 → 对话设置 → 技能（见对话设置）。
- 勾选这个对话要用的技能。
新增或删除技能文件夹后，列表很快会自动刷新；按 重新扫描 可以立即刷新。运行时总是按磁盘上的文件为准。列表先是 全局 一节，再按工作区各分一节（见对话设置）。每节标题上的文件夹按钮（打开全局配置目录 或 打开 {path} 的配置目录）会打开这一层的 skills/ 文件夹，不存在时先创建。对 WSL 或 SSH 工作区，它会在文件面板里打开那台机器上的这个文件夹。
- 模型的提示缓存还没过期时（默认 30 分钟），取消勾选上一次请求带过的技能会标成橙色，并在生效前询问一次，因为这会改变系统提示词。新增技能从不提醒。
- 任何模型都可以在对话中途增减技能，即使它不能中途增减工具。
- 内置的 mework 预设不选任何技能。
技能怎样交给模型
由技能页底部的 技能按需加载 开关决定。内置的 mework 预设会打开它。提示缓存未过期时，切换这个开关会标成橙色。
- 拼进提示词（关）：每个已选技能的正文都加进系统提示词，模型每次请求都能看到全部内容。
- 按需加载（开）：系统提示词里只列出每个技能的文件夹名和触发说明。觉得某个技能合适时，模型用 skill 工具取回它的正文。至少有一个已选技能能加载时才会出现这个工具，它从不需要审批。
按需加载时：
- 没有触发说明的技能不会出现在清单里，模型根本不知道它存在。请给每个技能写
description。 - 如果同时选了两个文件夹同名的技能（一个全局、一个在某个工作区，或者分别在两个工作区），运行会失败。请重命名其中一个文件夹，或者只选一个。
中途加入的技能
系统提示词保留对话开始时的那组技能，这样提示缓存不会失效。之后才勾选的技能会在当时的位置送达，时间线上显示为 送达了新增的技能 卡片；从这时起，它和一开始就在的技能一样生效。取消勾选的技能会在下一轮从系统提示词里移除。
子代理沿用父对话的技能和加载方式。
Mework SDK 技能
Mework SDK 内置在应用里，在每个对话的技能列表中排第一。它教模型配置 Mework 本身：技能、mcp.json、hooks.json、lsp.json、提示词档案、launch.json、MEWORK.md、规则与记忆，以及应用内各项设置在哪里。想让模型替你配置时，勾选它。
它随 Mework 版本更新，不能编辑或删除，也没有任何预设会选中它。
删除技能
点行上的垃圾桶按钮，等它变成 确认 后再点一次。这会删除整个文件夹，包括里面的脚本和参考文件。
选过这个技能的对话会保留选择，显示为 悬空；取消勾选之前，每次运行都会失败，并写明是哪个技能。
限制
| 项目 | 上限 |
|---|---|
SKILL.md 大小 |
256 KiB |
| 触发说明 | 1,024 个字符 |
| 系统提示词里技能、MCP 服务器、钩子几部分合计 | 1 MiB |
| 按需加载时，已选技能的正文合计 | 1 MiB |
| 对话开始后才加入的技能合计 | 1 MiB |
超过 1 MiB 时运行失败。少选几个技能，或者精简技能内容。
排查问题
列表里没有某个技能。 确认文件夹直接位于 skills/ 下、是真实文件夹而不是链接、里面有 SKILL.md、名称合规。WSL 或 SSH 工作区的 skills/ 文件夹要放在那台机器上。旧的 .naiword/skills/ 在同一层级没有 .mework/skills/ 时仍会被读取；把它移到 .mework/skills/ 后，需要重新勾选。
某行显示不可用。 悬停查看原因，通常是文件超过 256 KiB 或不是 UTF-8。对话选着它时，每次运行都会失败，直到修好文件或取消勾选。
某行显示悬空。 文件夹被改名、移动或删除，选择已对不上任何技能。取消勾选之前，每次运行都会失败；取消后再勾选技能的新行。
按需加载时模型从不使用某个技能。 检查它是否有 description，frontmatter 的键是否顶格。