！ 本篇文章將會介紹 agent skills，一個資料夾加一份 SKILL.md，讓 AI 在對的時機自己載入對的知識 :D

TL;DR: https://dev.benben.me/slides/s/ironman-15-agent-skills

本篇目標

讀完這篇你會學到：

• skill 的結構（資料夾 + SKILL.md + 參考文件）
• skills 與 commands / rules / MCP 的差別
• 寫一個自己的 skill 並控制存取權限

Skill 的核心思想：按需載入

rules（AGENTS.md）是永遠在場的常識，每個字都佔 context。skill 則相反：

一個 skill = 一包「名稱 + 簡介」的目錄。AI 平常只看到目錄，判斷任務需要時才載入全文。

這叫 progressive disclosure——圖書館不會把所有書攤在桌上，但書脊都看得到。context 佔用從「常駐全文」變成「常駐一行簡介」。

結構：一個資料夾 + SKILL.md

.opencode/skills/git-release/SKILL.md

SKILL.md 長這樣：

---
name: git-release
description: Create consistent releases and changelogs
---

## What I do

- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me

Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

front-matter 規則：

• name、description 必填
• name：1–64 字元、小寫英數加單一連字號、必須跟資料夾同名（regex：^[a-z0-9]+(-[a-z0-9]+)*$）
• description：1–1024 字元——這行就是 AI 決「要不要載入」的唯一依據，請具體，不要寫「幫忙處理 release」這種模糊話

尋找路徑

• .opencode/skills/<name>/SKILL.md（專案）
• ~/.config/opencode/skills/<name>/SKILL.md（全域）
• .claude/skills/ 與 .agents/skills/（相容 Claude Code 與通用 agent 慣例——直接沿用舊資產）

專案層會從目前目錄往上爬到 git worktree 根，沿途的 skills 都會收。

技能裡面還可以再放東西

資料夾裡不只能放 SKILL.md——還可以塞參考文件、範本、腳本。SKILL.md 裡寫「細節見 references/api-notes.md」，AI 載入技能後再按需讀。比起統傳的（嗯？統傳？）Skill 可以不用都寫成一大包，第二層的 lazy loading，大型知識庫也不爆 context。

AI 怎麼用 skill？

opencode 內建一個 skill tool。啟動時所有可用技能會列在 tool 描述裡：

<skill>
  <name>git-release</name>
  <description>Create consistent releases and changelogs</description>
</skill>

AI 看到任務吻合，就呼叫 skill({ name: "git-release" }) 載入全文，然後照著做。全程自動——你要做的只是把技能寫好。

權限控制

skills 也吃 permission 系統，pattern 支援萬用字元：

{
  "permission": {
    "skill": {
      "*": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

• allow：直接載入
• deny：對 AI 隱藏這個技能
• ask：載入前先問你

也能按 agent 覆寫——例如只讓某個專門 agent 用 documents-* 技能。要整個關掉 skills，把該 agent 的 skill tool 設 false 即可（tools: { skill: false }）。

跟其他擴充機制的差別

一個記憶法：rules 是常識、commands 是口頭禪、skills 是專業知識、tools 是雙手。

常見問題

Q：我的 skill 沒出現，怎麼 debug？
A：官方排查清單——SKILL.md 檔名要全大寫、front-matter 有 name 與 description、名稱跨所有位置不重複、沒有被 permission deny。

Q：skill 跟 AGENTS.md 引用外部文件（Day 12）比起來？
A：效果都是 lazy loading，但 skill 有「目錄化」的優勢：AI 主動看到目錄並判斷時機；AGENTS.md @ 引用則要靠你寫的規則提醒。知識單元愈大愈獨立，用 skill 愈划算。

Q：技能可以分享嗎？
A：資料夾 copy 或進 git 就能分享。Day 25 會介紹 Matt Pocock 的 skills 生態系——別人寫好的整套工程技能，裝了就能用。

小結

• Skill = 資料夾 + SKILL.md（name / description 必填），AI 按任務自動載入
• 支援 .opencode/skills/、全域、.claude/skills/、.agents/skills/
• permission 可 allow / deny / ask，可按 agent 覆寫
• 大知識包可塞參考文件做第二層按需載入

明日預告

Day 16：Custom tools——不滿足於「知識」？直接幫 AI 打造新的雙手。

有任何疑問但沒有 iT 邦幫忙帳號，或是想匿名提問？
歡迎到 https://dev.benben.me/q/P3C5U6 提問或加油打氣，沒意外的話會在完賽之後一起回答 :D