# 技能怎么写

一个技能就是一个文件夹。唯一必需的文件是 `SKILL.md`：开头一小段告诉 AI 这个技能用来做什么，后面用平实的话写做法。脚本和参考文件都是可选的。

## 文件夹

```text
weekly-summary/
├── SKILL.md          必需：开头 + 做法
├── scripts/          可选：技能要运行的代码
│   └── run.mjs
└── references/       可选：AI 需要时再读的材料
    └── format.md
```

文件夹名就是技能名。用小写字母、数字和连字符，比如 `weekly-summary`、`check-invoices`。

## SKILL.md

```markdown
---
name: weekly-summary
description: 把最近 7 天的会议记录总结成决定、未解决问题和带负责人的行动项。
  在要周总结、会议回顾、或问这周定了什么时使用。
---

# 每周总结

## 输入与结果
- 输入：工作区里的会议记录（.md、.docx 或 .pdf），文件名或第一行带日期。
- 结果：工作区里的 weekly-summary-YYYY-MM-DD.md。

## 做法
1. 列出最近 7 天的记录。一份都没有就说明并停止。
2. 从每份记录里取出决定、未解决问题和行动项。
3. 分三节写总结。行动项用表格：负责人（只写名）· 行动 · 截止日期，按负责人分组。
4. 保存文件。不要改动会议记录。

## 代表性检查
总结里的每个行动项都能在某份记录里找到，最近 7 天的每份记录都列在「来源」下。
```

### 开头（frontmatter）

| 字段 | 必需 | 作用 |
|---|---|---|
| `name` | 是 | 技能名，和文件夹名相同。可以用 `/名称` 直接运行 |
| `description` | 是 | 技能做什么，**以及什么时候用**。AI 只读这一段来判断要求对不对得上，所以要写进大家实际会说的话 |
| `entry` | 否 | 主脚本，比如 `scripts/run.mjs` |
| `resources` | 否 | 技能要用到的文件夹里其他文件的列表 |
| `disable-model-invocation` | 否 | 设为 `true` 时 AI 不会自己选用这个技能，只有你输入 `/名称` 时才运行 |

### 正文

像给新同事交代工作那样写做法。分三部分效果最好，这也是 Cowork 的技能创建工具一开始给你的结构：

- **输入与结果**：技能需要什么，「做完」是什么样子
- **做法**：步骤、限制（「不要改动会议记录」）和预期产出
- **代表性检查**：一个示例输入和你预期的结果，让 AI 能判断做对没有

AI 只在用到技能时才读完整正文，所以正文可以按工作需要写长。

## 脚本

工作里有一部分必须每次一模一样时（计算、文件转换、调用某个系统），就写成脚本。AI 运行它并使用它输出的内容。

- 脚本用 JavaScript 或 TypeScript（`.mjs`、`.js`、`.ts`）。Cowork 用自带的运行环境执行，不需要另外安装。
- 在你电脑上运行脚本前一定会先问你
- 脚本以你平常的权限运行。只用你自己或你信任的人写的脚本。

### 不经过 AI 直接运行的命令

技能也可以是一个普通命令：输入 `/名称` 加几个词，就直接运行它的脚本，不经过模型，并显示脚本输出的内容。开头这样写：

```yaml
---
name: count-files
description: 按文件类型统计工作区里的文件数量。
entry: scripts/run.mjs
x-shortcut:
  run: scripts/run.mjs
---
```

`/count-files` 后面的词会作为命令行参数传给脚本。跟 AI 说「做一个命令技能」，它会帮你设好。

## 文件夹放在哪里

| 位置 | 谁能用 |
|---|---|
| 工作区里的 `.agents/skills/` | 打开这个工作区的所有人 |
| 这台电脑的技能（Cowork 的 `skills/` 文件夹） | 只有你，所有工作区都能用 |
| 主目录下的 `~/.agents/skills` | 只有你；其他使用这个文件夹的工具也会读 |

平台和机构发布的技能是只读的。要改，先复制一份到你自己的技能里。见 [技能是什么](https://docs.micromeet.ai/zh/skills/what-are-skills.md)。

## 检查技能

说「检查 weekly-summary 技能」。Cowork 会检查开头字段、声明的文件是否存在、有没有留下模板占位符。格式检查通过不代表技能好用：要用真实的要求测一遍。