---
title: "使用 Agent Skills"
description: "理解 OpenCode Agent Skills：放在哪裡、怎麼寫、什麼時候載入，以及許可權如何控制。"
verifiedAt: "2026-05-09"
---

Agent Skill 是一份可以被 OpenCode 按需載入的操作說明。它平時只暴露名稱和描述，Agent 認為需要時，才透過原生 `skill` 工具載入完整 `SKILL.md`。

> [!NOTE]
> **這一篇用 10 分鐘換什麼**：你會知道 Skill 適合沉澱什麼，應該放在哪個目錄，`SKILL.md` frontmatter 怎麼寫，以及如何用許可權控制內部 Skill。

## 先給結論：Skill 是流程包，不是大號規則檔案

不要把 Skill 當成另一個 `AGENTS.md`。兩者職責不同：

| 內容 | 應該放哪裡 | 判斷標準 |
| --- | --- | --- |
| 專案長期規則 | `AGENTS.md` / Rules | 每次進入專案都要遵守 |
| 一次性命令入口 | Commands | 使用者明確呼叫 `/xxx` |
| 可複用操作流程 | Skill | 某類任務反覆出現，但不需要常駐上下文 |
| 角色和許可權邊界 | Agent | 需要固定“誰來做”和“能做什麼” |

Skill 最適合承載釋出流程、PR 審查流程、文件生成流程、遷移檢查清單、排障 SOP 這類可複用任務。臨時要求不要做成 Skill，否則庫會越來越臃腫。

## Skill 是怎麼被發現和載入的

OpenCode 會先發現可用 Skill，把名稱和描述放進 `skill` 工具說明裡。Agent 先看摘要，判斷需要時再載入完整內容。

```mermaid
flowchart LR
  Start[當前工作目錄] --> Walk[向上查詢到 git worktree]
  Walk --> Project[專案級 skills]
  Home[使用者主目錄] --> Global[全域性 skills]
  Project --> List[可用技能列表<br/>name + description]
  Global --> List
  List --> Decide{Agent 判斷是否需要}
  Decide -->|需要| Load[呼叫 skill 工具載入 SKILL.md]
  Decide -->|不需要| Skip[不佔用上下文]
```

這個機制的關鍵是：`description` 寫得越具體，Agent 越容易在正確時間載入它。

## 放在哪裡

為每個 Skill 建立一個資料夾，並在裡面放 `SKILL.md`。OpenCode 會搜尋這些位置：

| 位置 | 適合場景 |
| --- | --- |
| `.opencode/skills/<name>/SKILL.md` | 當前專案專用 |
| `~/.config/opencode/skills/<name>/SKILL.md` | OpenCode 全域性複用 |
| `.claude/skills/<name>/SKILL.md` | 相容專案裡的 Claude Code Skill |
| `~/.claude/skills/<name>/SKILL.md` | 相容全域性 Claude Code Skill |
| `.agents/skills/<name>/SKILL.md` | 相容其他 Agent 目錄 |
| `~/.agents/skills/<name>/SKILL.md` | 全域性 Agent 相容目錄 |

選擇順序很簡單：

1. 只服務當前儲存庫，放專案目錄。
2. 多個儲存庫都要用，放全域性目錄。
3. 已經有 Claude Code Skill 庫，優先複用相容入口，不要複製一份大型目錄。

> [!IMPORTANT]
> Skill 的位置就是影響範圍。專案專用 Skill 不要放全域性，否則其他儲存庫可能誤觸發。

## `SKILL.md` frontmatter 怎麼寫

每個 `SKILL.md` 必須以 YAML frontmatter 開頭。官方識別這些欄位：

| 欄位 | 是否必填 | 用法 |
| --- | --- | --- |
| `name` | 必填 | Skill 名稱，必須和目錄名一致 |
| `description` | 必填 | 觸發條件和產出邊界 |
| `license` | 可選 | 分發或團隊共享時寫清楚 |
| `compatibility` | 可選 | 標明相容平臺，例如 `opencode` |
| `metadata` | 可選 | 字串到字串的補充資訊 |

未知欄位會被忽略，不要把關鍵約束寫在 OpenCode 不識別的 frontmatter 欄位裡。

## 名稱和描述怎麼判斷

`name` 要滿足：

- 長度 1-64 個字元。
- 只用小寫字母、數字和單個連字元。
- 不以 `-` 開頭或結尾。
- 不包含連續 `--`。
- 與包含 `SKILL.md` 的目錄名一致。

等效規則可以記成：

```text
^[a-z0-9]+(-[a-z0-9]+)*$
```

`description` 長度為 1-1024 個字元。它不是廣告語，而是給 Agent 的觸發條件。不要寫 `help with git`，要寫清楚“什麼時候用、產出什麼、有哪些邊界”。

## 一個可用的最小 Skill

檔案：`.opencode/skills/release-check/SKILL.md`

```md
---
name: release-check
description: Use when preparing a release; checks diff, changelog, tests, version bump, and publish command
license: MIT
compatibility: opencode
metadata:
  workflow: github-release
---

## When to use

Use this when preparing a tagged release or release candidate.

## Steps

1. Read the current diff and changelog.
2. Confirm tests and version bump.
3. Draft release notes.
4. Produce a publish command for human review.

## Boundaries

Do not publish automatically.
Do not include secrets or private customer names.
```

這個 Skill 的重點不是寫得長，而是觸發條件、步驟和邊界都清楚。

## 許可權如何控制

在 `opencode.json` 裡可以用模式控制 Agent 能訪問哪些 Skill：

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "skill": {
      "*": "ask",
      "release-check": "allow",
      "internal-*": "deny"
    }
  }
}
```

| 許可權 | 行為 |
| --- | --- |
| `allow` | 允許直接載入 |
| `deny` | 對 Agent 隱藏並拒絕訪問 |
| `ask` | 載入前先確認 |

模式支援萬用字元。比如 `internal-*` 可以覆蓋 `internal-docs`、`internal-tools` 等內部技能。

> [!WARNING]
> 團隊內部 Skill 不要預設全開。涉及釋出、憑據、客戶專案、生產環境的 Skill，先設為 `ask` 或 `deny`。

## 按 Agent 覆蓋許可權

你也可以讓不同 Agent 使用不同 Skill 許可權。比如審查 Agent 可以使用 `documents-*`，但普通聊天 Agent 看不到內部發布 Skill。

自定義 Agent frontmatter 示例：

```yaml
---
permission:
  skill:
    "documents-*": "allow"
    "internal-*": "ask"
---
```

內建 Agent 可以在 `opencode.json` 裡覆蓋：

```jsonc
{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "research-*": "allow"
        }
      }
    }
  }
}
```

## 什麼時候停用 Skill 工具

有些 Agent 不應該載入 Skill：

- 只做規劃、不執行流程的 Agent。
- 不應該接觸內部資料的 Agent。
- 臨時測試 Agent，避免誤載入團隊 Skill。

可以直接關閉 `skill` 工具。關閉後，可用技能列表會完全省略。

```yaml
---
tools:
  skill: false
---
```

## 排查載入問題

如果某個 Skill 沒顯示，按這個順序查：

1. 檔名是否是全大寫 `SKILL.md`。
2. frontmatter 是否包含 `name` 和 `description`。
3. `name` 是否和目錄名完全一致。
4. 當前啟動目錄是否位於目標 git 工作樹內。
5. 不同位置是否有同名 Skill 衝突。
6. 許可權是否被設為 `deny`。

## 新手常見坑

- 描述太泛，Agent 不知道什麼時候載入。
- Skill 太大，把整個團隊手冊塞進一個檔案。
- 目錄名和 `name` 不一致。
- 專案專用 Skill 放到全域性，導致其他儲存庫誤觸發。
- 把真實金鑰、賬號、客戶資料寫進 Skill。
- 只會用一次的 prompt 也做成 Skill。

## 接下來去哪

<Cards>
  <Card title="配置 Agents" href="/zh-Hant/docs/opencode/official/02-agents-skills/agents">
    Skill 只定義流程，Agent 才定義誰來做、能不能改檔案、用什麼許可權。
  </Card>
  <Card title="安裝外掛" href="/zh-Hant/docs/opencode/official/02-agents-skills/plugins">
    如果你要改變 OpenCode 執行時行為，再繼續看 Plugin。
  </Card>
  <Card title="編寫規則" href="/zh-Hant/docs/opencode/official/02-agents-skills/rules">
    長期專案約束應該放 Rules，不要塞進 Skill。
  </Card>
  <Card title="Agents、Skills、Plugins 怎麼分" href="/zh-Hant/docs/opencode/understanding/05-agents-skills-plugins">
    回到完整分層，判斷某個經驗該沉澱到哪一層。
  </Card>
</Cards>

## 官方資料

- [OpenCode Agent Skills](https://opencode.ai/docs/skills/)
- [OpenCode configuration](https://opencode.ai/docs/config/)
