建立你的第一個技能

學完你能做什麼

完成本教學後，你將能夠：

• 建立符合規範的技能目錄結構
• 編寫正確的 SKILL.md Frontmatter
• 理解技能的各個組成部分
• 讓 OpenCode 自動發現並載入你的技能
• 測試技能是否正常工作

你現在的困境

你可能遇到了這些情況：

• 想為專案建立專用技能，但不知道從哪開始
• 嘗試寫了一個 SKILL.md，但外掛找不到
• 技能被發現了，但載入時報錯「YAML 解析失敗」
• 不確定 Frontmatter 裡應該填哪些欄位

這些問題都是因為不了解技能的結構規範。OpenCode Agent Skills 遵循 Anthropic 的 Agent Skills 規範，有固定的格式要求。

什麼時候用這一招

建立技能適用於以下情境：

• 專案特定工作流程：為某個專案客製化的程式碼審查、部署流程
• 團隊規範：統一團隊的 commit 規範、程式碼風格檢查
• 工具整合：整合常用 CLI 工具（如 git、docker）
• 知識沉澱：將常用操作步驟文件化，供 AI 隨時呼叫

🎒 開始前的準備

在開始之前，請確認：

前置檢查

• ✅ 已安裝 OpenCode Agent Skills 外掛（參考安裝教學）
• ✅ 熟悉基本的命令列操作（mkdir、cd、ls）
• ✅ 有一個專案目錄用於存放技能

核心思路

OpenCode Agent Skills 的技能是一個目錄，目錄中必須包含 SKILL.md 檔案。這個檔案有兩部分：

1. YAML Frontmatter：技能的中繼資料（名稱、描述等）
2. Markdown 正文：AI 執行時遵循的指導內容

外掛會從多個位置自動發現技能（按優先順序排序）：

1. .opencode/skills/              (專案級 - OpenCode)
2. .claude/skills/                (專案級 - Claude Code)
3. ~/.config/opencode/skills/     (使用者級 - OpenCode)
4. ~/.claude/skills/              (使用者級 - Claude Code)
5. ~/.claude/plugins/cache/        (外掛快取)
6. ~/.claude/plugins/marketplaces/ (已安裝外掛)

同一名稱的技能，第一個匹配的生效。

跟我做：建立第一個技能

我們將建立一個簡單的「hello-world」技能，用於演示基本結構。

第 1 步：建立技能目錄

為什麼 技能必須放在特定的目錄中，外掛才能自動發現。

操作

# 在專案根目錄建立技能目錄
mkdir -p .opencode/skills/hello-world

你應該看到：

專案根目錄/
└── .opencode/
    └── skills/
        └── hello-world/

第 2 步：編寫 SKILL.md

為什麼 SKILL.md 是技能的核心檔案，包含中繼資料和指導內容。

操作

在 .opencode/skills/hello-world/SKILL.md 中寫入：

---
name: hello-world
description: A simple greeting skill for demonstration
---

# Hello World Skill

This is a demonstration skill that shows how to create a basic skill.

## Usage

Use this skill when you need to greet users or demonstrate skill functionality.

## Example

When asked "Say hello to the user", respond with a friendly greeting.

你應該看到：

.opencode/skills/hello-world/
└── SKILL.md

第 3 步：驗證技能被發現

為什麼 確保 Frontmatter 格式正確，外掛能正確解析。

操作

在 OpenCode 中詢問：

列出所有可用的技能

你應該看到： 外掛返回的技能列表中包含 hello-world。

或者直接呼叫工具：

get_available_skills()

預期輸出：

Available skills:
- hello-world: A simple greeting skill for demonstration

第 4 步：載入並測試技能

為什麼 驗證技能內容能正確注入到會話上下文。

操作

在 OpenCode 中：

載入 hello-world 技能

你應該看到：

Skill 'hello-world' loaded successfully.

Available scripts: (none)
Available files: (none)

SKILL.md 內容已注入到上下文。

第 5 步：驗證技能可用

為什麼 確認 AI 能理解並遵循技能指導。

操作

詢問 AI：

根據 hello-world 技能，向我打招呼

你應該看到： AI 根據技能內容輸出友好的問候。

檢查點 ✅

完成上述步驟後，檢查以下幾點：

• [ ] .opencode/skills/hello-world/SKILL.md 檔案存在
• [ ] get_available_skills() 能列出 hello-world 技能
• [ ] use_skill("hello-world") 成功載入，無錯誤
• [ ] AI 能理解並遵循技能內容

如果任何一項不通過，請查看下面的「踩坑提醒」。

踩坑提醒

技能找不到？

錯誤現象	可能原因	解決方法
外掛找不到技能	目錄名或檔名錯誤	確認檔名是 SKILL.md（全大寫）
外掛找不到技能	Frontmatter 格式錯誤	檢查 --- 是否存在，前後是否有空行
外掛找不到技能	name 欄位不符合規範	name 必須是小寫字母、數字、連字元

解析失敗？

錯誤現象	可能原因	解決方法
YAML 解析失敗	Frontmatter 格式不對	確保使用正確的 YAML 格式，字串用引號包裹
驗證失敗	name 包含大寫字母或特殊字元	name 欄位只能是小寫字母、數字、連字元
驗證失敗	description 為空	description 必須有值

常見錯誤範例

# ❌ 錯誤：name 包含大寫字母
---
name: HelloWorld
description: A skill
---

# ❌ 錯誤：name 包含空格
---
name: hello world
description: A skill
---

# ❌ 錯誤：name 包含特殊字元（除連字元）
---
name: hello_world
description: A skill
---

# ✅ 正確
---
name: hello-world
description: A skill for demonstration
---

Frontmatter 欄位必填性

欄位	是否必填	約束	範例
name	✅ 是	小寫字母數字連字元	my-skill
description	✅ 是	非空字串	A skill for git management
license	❌ 否	開源協議名稱	MIT
allowed-tools	❌ 否	工具名稱陣列	["read", "write"]
metadata	❌ 否	key-value 物件	{"namespace": "project"}

本課小結

本教學講解了：

1. 技能目錄結構：.opencode/skills/<skill-name>/SKILL.md
2. Frontmatter 格式：YAML 格式，包含 name 和 description 必填欄位
3. 技能發現規則：從 6 個位置按優先順序自動發現
4. 技能載入流程：透過 use_skill 工具載入內容到上下文

現在你已經掌握了建立技能的基礎知識。接下來，你將學習外掛的技能發現機制，了解它如何自動掃描和管理多個技能。

下一課預告

下一課我們學習 技能發現機制詳解。

你會學到：

• 技能發現的 6 個位置及優先順序規則
• 同名技能的去重邏輯
• Claude Code 技能的相容機制
• 如何查詢技能的來源和命名空間

---

附錄：原始碼參考

點選展開查看原始碼位置

更新時間：2026-01-24

功能	檔案路徑	行號
Frontmatter Schema 定義	src/skills.ts	105-114
解析 SKILL.md 檔案	src/skills.ts	122-167
查詢技能腳本	src/skills.ts	59-99
技能發現優先順序列表	src/skills.ts	241-246
解析 YAML Frontmatter	src/utils.ts	41-49

關鍵常數：

• 腳本最大遞迴深度：maxDepth = 10
• 跳過的目錄：node_modules, __pycache__, .git, .venv, venv, .tox, .nox

關鍵函式：

• parseSkillFile()：解析 SKILL.md 檔案，驗證 Frontmatter 並擷取中繼資料
• findScripts()：遞迴查詢技能目錄下的可執行腳本
• discoverAllSkills()：從多個位置發現所有技能