Skill 是什麼？跟手機 App 有什麼不一樣

為什麼要學 Skill 這個東西

你到目前為止用 Pi Agent 應該已經覺得蠻好用了——第 7 章教你開對話問問題、第 4 章教你看懂工作區。但你有沒有發現一個怪現象：每一次新開的 session，你都要重講一遍同樣的背景？

• 「幫我看一下冰箱的照片，列出快過期的東西」——AI 要先問「你家冰箱多大？你的分類邏輯是什麼？肉類放上層還下層？」
• 「幫我排這禮拜家事」——AI 要先問「你家幾個人？誰做什麼？平日還是週末？」
• 「幫我寫一個晚上關客廳燈的自動化」——AI 要先問「客廳燈的 entity_id 是什麼？你的 HA 是哪版？要用 device 還是 entity 觸發？」

這些「背景資訊」跟「做這件事的正確步驟」，每一次都重講就是浪費——浪費你的時間、浪費 AI 的 tokens（第 9 章講過每個 token 都在燒錢）。更慘的是每次講都可能講漏一點，結果 AI 每次做出來的東西風格都不一樣。

Skill 就是幹掉這件事的東西。把「一項專門手藝的作業步驟」寫成一份手冊放在固定位置，Pi Agent 每次開新 session 都會自動把手冊摘要塞進 AI 的腦袋，AI 就會知道：「喔這台機器有裝『冰箱盤點』這個手藝，遇到相關問題我就照那份手冊做，不用重問。」

會用 Skill 的人，Pi Agent 就變成一個「越用越懂你家」的助手。不會用 Skill 的人，Pi Agent 就永遠是個「每次都要重講的路人」。這章要建的心智模型只有一句：Skill 是給 AI 讀的工作手冊，教一次它記得。

用「教鐘點阿姨的工作手冊」比喻 Skill

抽象的名詞先落到具體情境。想像你家最近請了一位新來的鐘點阿姨（就是 AI），她每週來三次幫忙做家事。第一次來的時候你要交代一堆事：

• 「這個垃圾桶要分乾濕、廚餘另外裝進門口那個綠色小桶」
• 「冰箱裡的食材要看標籤日期，過期的先挑出來放廚房中島上讓我看，不要直接丟」
• 「洗好的衣服，白色掛陽台左邊、深色掛右邊、內衣掛陰乾架不要曬太陽」

結果她下次來，你不在家。她一進門臉茫然，因為她全忘光了——要嘛把混合垃圾整袋丟出去、要嘛把過期優格直接倒掉、要嘛把你的黑色衣服曬到褪色。你回家看到就爆炸。

怎麼辦？把這些交代寫成一份「工作手冊」，護貝好貼在冰箱門上。她每次來自己看一遍，你不在也知道該怎麼做。這份工作手冊就是 Skill。

Skill 的三個特徵，對應到工作手冊：

Skill vs 手機 App vs HACS 元件

你熟的兩個東西是手機 App 和 HACS 元件（第 4 章提過 HA 的社群商店叫 HACS）。Skill 跟它們長得有點像但根本不同。一次對照清楚：

最關鍵的差別是「Skill 不是一段會執行的程式，而是一份會被 AI 讀進腦袋的指示」。App 跟 HACS 元件被裝上去之後是「多了一個功能可以按」，Skill 被裝上去之後是「AI 多會了一項本事」。前者是外掛，後者是家教。

Skill 存在哪裡？資料夾結構長怎樣

Pi Agent 把 Skill 存在一個固定位置：

/data/pi-agent/skills/
├── fridge-check/
│   ├── SKILL.md
│   └── examples/
│       └── sample-photo-analysis.md
├── ha-automation-templates/
│   ├── SKILL.md
│   ├── motion-light.yaml
│   └── arrive-home-ac.yaml
└── video-pitch/
    ├── SKILL.md
    ├── narrator-voice-config.md
    └── scene-templates/
        └── intro.html

幾個重點：

• 一個 skill = 一個資料夾。資料夾名字就是這個 skill 的識別，例如 fridge-check。
• 資料夾裡一定要有一個 SKILL.md——這是 AI 會讀的主檔，缺這個 Pi Agent 掃描時會跳過。
• 其他檔（YAML 範本、範例照片、輔助說明）都可以放進來，AI 需要時會被指引去讀。這叫「漸進揭露」（progressive disclosure）——主檔給摘要，細節分散在檔案裡按需展開，避免每次都把幾百 KB 塞進 context。
• 資料夾位置在 /data/pi-agent/skills/，這個 /data/ 是 HA add-on 的持久化資料區（在容器內另有 ~/.pi/agent/skills 的符號連結指到同一位置，CLI 跟 UI 才不會各寫各的）。HA add-on 的 /data/ 預設會被 HA 完整備份收錄，所以只要你有排 HA snapshot／backup，Skill 就會跟著回來（video-tools 那個 720MB 快取按設計是不進備份的，兩者要分開想）。

你其實不用手動去這個資料夾操作——Pi Agent 有 Skills 面板可以裝、可以移除（第 15 章詳講）。但知道底下長這樣，遇到問題時比較好排查。

Pi Agent 怎麼把 Skill「餵」給 AI 讀

知道 Skill 是什麼、存哪裡之後，下一個關鍵問題：AI 怎麼會知道我裝了哪些 Skill？又不是它自己去掃我的資料夾。答案在 pi-web 每次開新對話時做的「開場動作」。

第一步：pi-web 掃描 skills 資料夾

當你需要新的 skill 清單生效時（通常是按「新對話」開新 session；某些版本會在你打開對話面板或按 reload skills 時做），pi-web 後端會去 /data/pi-agent/skills/ 底下把所有 */SKILL.md 讀一遍。它不是讀整份，只讀開頭的 frontmatter（YAML 開頭區塊），把每個 skill 的 name 跟 description 抽出來。目前版本沒有可靠的即時檔案監聽，所以你在檔案系統改了 SKILL.md 後，最保險是開新對話讓它重掃一次。

第二步：組成一段「可用 skill 清單」塞進 system prompt

抽出來的清單會被組成一段類似下面的文字，塞進 system prompt（AI 每次對話最一開始收到的「開場指示」）。實際的區塊標籤與格式會隨 Pi Agent／pi-coding-agent 版本變動，下面只是示意——你自己實際看到的可能是 <available_skills>、<skills>、或另一種 Markdown 標題包起來的區塊，重點是清單本身：

<available_skills>
- fridge-check: 給冰箱食材照片，幫使用者列出臨期食材、建議晚餐菜色
- ha-automation-templates: 常見 HA 自動化模板（動作偵測開燈、到家開空調等）
- video-pitch: 產出 60 秒帶字幕的產品介紹影片
</available_skills>

AI 一睜眼就看到「這台機器有這三個手藝可用」。要看你這台實際塞進去的長什麼樣，去打開 System prompt 面板往上滑（下一節會講）。

第三步：AI 判斷該不該用

你問「幫我看冰箱裡的照片列出快過期的」時，AI 掃過清單就會發現「有 fridge-check 這個手藝」，然後主動去讀 fridge-check/SKILL.md 的完整內容（含操作步驟、注意事項、範例參考），照著做。

你問「今天台北天氣怎樣」的時候，AI 掃一遍發現沒有相關的 skill，就照它自己的一般知識回答，不會硬要用哪個 skill。

常見的五類 Skill，你會裝到哪些

Skill 的用法百百種，但實務上會遇到的大概就這五類。看過一輪你就有感覺哪些適合自己家：

剛開始不用一次裝滿。建議順序：先裝一兩個「家事類」感受什麼是 skill，再看你日常最常問 AI 什麼，把那件事寫成 skill。整理心得後再去 GitHub 找別人做的 skill 補齊其他類別（第 15 章教怎麼裝）。

怎麼看目前這個 session 讀到哪些 Skill

裝完 skill 之後，你可能會想確認一下「AI 這次對話到底有沒有看到它」。Pi Agent 有幾個地方可以確認（實際按鈕文字可能因 pi-web 版本略有差異，找語意相符的就對了）：

1. 方法 A：System prompt 面板

   在 pi-web 工作區的操作列上找「System prompt」／「System」／「系統提示」之類語意的按鈕（第 4 章導覽過工作區位置）點開。裡面會顯示這次 session 完整的開場指示，往上滑就能看到列出可用 skill 的那一段，包含所有目前生效的 skill 名字＋描述。唯讀，不能在這裡改內容。

2. 方法 B：Skills 面板（管理用）

   同一區操作列找「Skills」入口，這個面板是給你管理的：可以看清單、裝新的、移除。按鈕文字（例如「Install / Add from URL / Remove」還是換成中文的「安裝／從網址新增／移除」）看你的 pi-web 版本，功能是一樣的。列出來的東西跟 System prompt 那段應該一致，除非你剛裝完還沒開新 session。

3. 方法 C：直接問 AI

   最偷懶但也最直觀——在對話裡打「你這次看得到哪些 skill？」AI 會照著它讀到的清單唸給你聽。適合快速確認又不想離開對話畫面時。

如果 System prompt 面板打開看不到列出 skill 的那一段，通常是兩個原因：（1）你完全沒裝任何 skill，Pi Agent 這時候可能會省略這一塊，AI 就完全依賴一般知識回答，一樣能用；（2）你的 pi-web 版本比較舊，那時候還沒把這段獨立顯示，升級 Pi Agent 就有了（第 21 章會講升級）。

一個 Skill 的最小骨架（給你先看，第 16 章實作）

雖然這章不教你怎麼寫 skill（那是第 16 章的工作），但先看一眼骨架長什麼樣，你對「Skill 是文字」這件事會更有感覺。

假設我要做一個叫 fridge-check 的 skill，最小可用版本只需要一個檔：/data/pi-agent/skills/fridge-check/SKILL.md，內容如下：

---
name: fridge-check
description: 使用者傳冰箱食材照片時，列出臨期食材（3 天內到期）並用剩下食材建議一道晚餐菜色
---

# 冰箱盤點手藝

當使用者傳冰箱內部照片時：

1. 逐項辨識可見食材，記下品項與可讀到的到期日
2. 挑出 3 天內到期的品項（用今天日期反推），列成「臨期清單」
3. 從剩下食材裡挑 3-5 樣可搭配的，建議一道台式家常菜
4. 用繁體中文回覆，格式：先臨期清單、再建議菜色、最後附一句備註提醒

## 注意事項

- 分不清楚的品項標「不確定」不要瞎猜
- 冷凍區與冷藏區分開列
- 使用者沒問就不要主動推銷食譜網站

拆解一下：

• 三橫線包起來的 YAML 前綴（叫 frontmatter）是給 pi-web 掃的。name 決定這個 skill 的識別、description 決定 AI 什麼時候會想到用它。這兩個欄位是 mattpocock/skills 慣例裡的核心欄位，實務上都寫；缺 description 的 skill AI 幾乎不會主動想到用。
• 三橫線後面全部是 Markdown 純文字，寫給 AI 看的操作步驟、注意事項、範例。愛寫多長就多長。
• 沒有任何程式碼、沒有 API 呼叫、沒有 Python——這就是為什麼「會寫中文就會寫 skill」。
• 資料夾內最小只要一個 SKILL.md 就會被掃到；其它檔（範例、YAML 範本、子文件）都是可選，主檔會指引 AI 什麼時候該去讀哪個。

這樣一個檔案存進 /data/pi-agent/skills/fridge-check/SKILL.md，開新對話，AI 就會知道自己會「冰箱盤點」這件事。就這樣。

Skill 跟「快速命令」／「手勢」不一樣

Pi Agent 或其他 AI 工具你可能還聽過「快速命令」（quick command）、「Prompt 模板」、「手勢」（gesture）這幾個詞。它們跟 Skill 都有「省重複打字」的味道，但機制根本不同，別搞混。

白話講：快速命令是「你懶得打字，讓工具幫你打」；Skill 是「你懶得每次教 AI，讓 AI 記住怎麼做」。前者省你的手指，後者省 AI 的腦袋。兩個可以搭配用——例如做一個 /整理發票 的快速命令，內容是「請用 receipts-parser skill 幫我把上傳的照片整理成表格」。

常見卡關

1. 我打開右上角看不到 System prompt 面板

   兩個可能：（1）你的 pi-web 版本較舊，那時候 System prompt 面板還沒獨立出來。到 HA 的 Add-ons 頁面看 Pi Agent 的更新提示，升到最新版就有（第 21 章會講升級注意事項）。（2）你在手機的窄畫面看，面板按鈕會被收進漢堡選單裡，展開選單找一下。

2. 我裝了 skill 但 AI 好像沒用它

   先確認三件事：（a）開新對話——舊 session 是在你裝 skill 之前開的，那次不會吃到；（b）打開 System prompt 面板看 available_skills 裡有沒有它的名字，沒有的話代表 pi-web 沒掃到，通常是 SKILL.md 的 frontmatter 語法錯了（三橫線少一條、YAML 縮排錯、缺 name 或 description）；（c）description 太模糊——AI 看不出這個 skill 該在什麼問題觸發，改成明確的「使用者做 X 時，我要 Y」句型。

3. Skill 太多了，AI 反應變慢也變花錢

   因為每個 SKILL.md 的 description 都會被塞進 system prompt，裝到幾十上百個時 context 開場就先吃掉幾千 token，每一輪對話都在燒。健康作法：（a）每季清一次「半年沒用到的 skill」；（b）description 寫短一點，主檔內容放操作細節 AI 需要時才讀；（c）把只有偶爾用的 skill 放到 ~/skills-archive/（隨便找個 pi-agent 掃不到的位置）備份起來，需要時再搬回去。

4. 兩個 skill 的 name 撞了

   Pi Agent 掃描時如果遇到兩個 SKILL.md 都寫 name: fridge-check，行為沒有正式保證——實務觀察到有些版本是後掃到的覆蓋前一個、有些版本是兩個都塞進去讓 AI 自己猜、也可能直接跳出錯誤日誌。掃描順序也不一定是檔名字母序。不要依賴任何一種行為；解法只有一個：把資料夾名字或 name 欄位改掉不衝突，例如一個叫 fridge-check 一個叫 fridge-check-strict，然後開新對話重掃。

5. 我改了 SKILL.md 但 AI 還是照舊行為

   Pi Agent 目前沒有可靠的即時檔案監聽——你在檔案系統修改 SKILL.md 後，多半要等到「開新對話」或「重新載入 skills」那個時機才會被重掃進 context。實務保險做法：直接按新對話（不是重新整理頁面），然後打開 System prompt 面板看 description 是不是你剛改的那句，確認新版真的進去了。

6. 裝了別人的 skill 之後 AI 做出奇怪的事

   八成是 SKILL.md 裡有你沒注意到的「額外指令」。第三方 skill 的內容你有義務先讀過——就跟裝陌生 HACS 元件之前該讀一下 README 一樣。移除方式：到 Skills 面板點該 skill 對應的移除按鈕（版本不同顯示可能是 Remove／Uninstall／移除），或走 CLI 用 podman exec -it pi-web pi uninstall <name>，最後手段是 SSH 進 HA 直接砍 /data/pi-agent/skills/<那個資料夾>。

常見問題