# 技能怎麼寫

一個技能就是一個資料夾。唯一必需的檔案是 `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-tw/skills/what-are-skills.md)。

## 檢查技能

說「檢查 weekly-summary 技能」。Cowork 會檢查開頭欄位、宣告的檔案是否存在、有沒有留下模板佔位符。格式檢查透過不代表技能好用：要用真實的要求測一遍。