為什麼你一直在解釋同一件事

你現在應該已經對話過幾次了。一個限制很快就會冒出來：每個新 Session 都是從零開始。兩個很平常的請求，換來的都是反問：

每次請求都要重打一遍這些背景，花的是你的時間跟輸入 token。這也讓結果變得不穩定：某天你忘了提上層是冷凍庫，拿到的答案就不一樣了。

一套程序，寫下來一次就好

Skill 把這些背景存進一個檔案裡。新 Session 開始時，Pi Agent 會給模型每個已安裝 Skill 的簡短摘要；當一個請求對上其中一個時，模型會去讀完整的程序，而不是反過來問你。

四件事讓 Skill 運作起來就像那張卡片：

• 它放在一個固定的地方。 在 /data/pi-agent/skills/底下，這是 Pi Agent 會去找的地方。
• 它有名字跟摘要。 SKILL.md 最上面的 name 跟 description 欄位。
• 細節收著不展開。 模型先拿到摘要，只有請求真的需要時才會去讀完整的指示。
• 你只安裝一次。 每個新 Session 都會拿到它，你什麼都不用做。

是指引，不是一支會執行的程式

Skill 看起來很像一個 App 或一個 HACS 整合，因為這三者都是在擴充一個系統能做的事。但它的運作方式從根本上不同，這個差異在安全性上很重要。

各自一個資料夾，一個真正重要的檔案

Pi Agent 把 Skill 放在一個固定的位置： /data/pi-agent/skills/。每個 Skill 各自一個資料夾，每個資料夾裡必須有一個 SKILL.md。沒有這個檔案的資料夾會被跳過。

flowchart TD
  R["/data/pi-agent/skills/"] --> A["fridge-check/"]
  R --> B["ha-automation-templates/"]
  R --> C["video-pitch/"]
  A --> A1["SKILL.md - 必須"]
  A --> A2["examples/ - 選用"]
  B --> B1["SKILL.md - 必須"]
  B --> B2["motion-light.yaml - 選用"]
  C --> C1["SKILL.md - 必須"]
  C --> C2["scene-templates/ - 選用"]

關於這個路徑有兩點要注意。在容器裡， ~/.pi/agent/skills 這個符號連結指向同一個地方，所以命令列跟介面操作的是同一批檔案。而且 Home Assistant 的完整備份包含附加元件的 /data/ ，這是預設就會包含的，所以還原之後你的 Skill 也會跟著回來。那 720MB 的影片工具快取是刻意排除在外、另外處理的。

你平常會透過 Settings 裡的 Skills 分頁管理這一切，而不是直接進目錄操作。還沒裝任何東西的時候，長這樣。

Settings 裡的 Skills 分頁還沒裝任何東西。也沒有什麼壞掉——就是還沒存任何程序而已。

• Skills 是對話框頂部五個分頁之一，位在 Models 跟 Sub-agents 中間。這裡就是它的家。
• No skills found 在左欄，這是你安裝任何東西之前的正常狀態。Pi Agent 一個 Skill 都沒有照樣運作得很好。
• + Add skill 在同一欄的最下面。第 10 篇會講按下去之後發生什麼事。
• Select a skill 是右邊面板的預留文字。等左欄有東西之後，這個面板就會顯示那個 Skill 的細節。

模型從來不會自己去看你的資料夾

這一段解釋了之後幾乎每個「為什麼它不理我的 Skill」的問題。遠端的模型看不到你的硬碟。是 Pi Agent 幫忙看，再告訴模型裡面有什麼。

1. 步驟 1

   Pi Agent 掃描資料夾

   pi-web 後端讀取每一個 */SKILL.md 底下的 /data/pi-agent/skills/ ，抓出 name 跟 description ，從最上面的 YAML frontmatter 裡取出來。這通常在你點「New conversation」時發生；有些版本點「Reload Skills」也會重新整理。

2. 步驟 2

   這些名字跟摘要會進入 system prompt

   這份清單會加進開啟 Session 的那些指令裡。外層的包裝方式因 Pi Agent 跟 pi-coding-agent 版本而異—— <available_skills>、 <skills>，或一段 Markdown。不管哪一種，內容都一樣：只有名字跟描述，別無其他。

3. 步驟 3

   模型自己判斷有沒有哪個用得上

   問一張冰箱照片，它就能對上 fridge-check，接著讀完整個檔案照著做。問不相關的事，它就不理會這份清單。

菜單大概長這樣：

在真正打開某一個之前，這個區塊就是模型對你 Skill 的全部認識。所以那個 description 做的就是讓 Skill 被注意到的全部工作。

自己親眼看這份清單

你不用只是聽信這件事。 System 在頂部工具列的按鈕，會打開 System prompt 面板，顯示這個 Session 一開始拿到的指令。

System prompt 面板你還沒打任何字之前，模型被告知的一切。

• 「You are an expert coding assistant operating inside pi」 是文字的開頭。這是模型實際收到的指令——如果這裡沒有點出某個 Skill 的名字，模型就不知道它存在。
• Available tools 列出四個，各佔一行：read、bash、edit、write。清單下面那行補充說，一個專案可能還會給模型其他自訂工具，加在這幾個之外。
• Guidelines 接著是一些內部規則，例如檔案操作要用 bash ，還有用 read 而不是 cat 來檢查檔案內容。
• 這段文字 會延伸到看得見的範圍之外。往下捲能看到 Guidelines 剩下的部分，等你裝了 Skill 之後，還會看到列出這些 Skill 的段落。

這也是確認新裝的 Skill 有沒有真的送進這個 Session 最快的方法：打開面板，往下捲到 Skills 段落，找那個名字。這一段的標籤跟樣式因 Pi Agent 版本而異，所以要看名字跟描述，不要死認標題。上面這張圖拍自一台沒裝任何 Skill 的機器，這也是為什麼看得到的文字從工具直接接到規則，中間沒有 Skills 段落。

完全沒有 Skills 段落，代表要嘛什麼都沒裝（Pi Agent 就不會顯示這段），要嘛你的 pi-web 版本太舊、不會單獨顯示，需要升級。

一個檔案，裡面沒有任何程式碼

實際上大部分 Skill 都落在五個領域裡：家事流程，例如垃圾分類跟冰箱盤點；Home Assistant 自動化範本，像是動作感應開燈跟到家自動調空調；固定格式的影片製作；CSV、log、收據這類資料處理；還有外部工具，例如 Notion、Google 日曆或 Telegram 機器人。

檔案本身比大家想的要小。一個能用的 fridge-check Skill 只需要一個檔案，就在 /data/pi-agent/skills/fridge-check/SKILL.md。開頭大概長這樣：

三條橫線中間的部分是 frontmatter——Pi Agent 只解析這一段。底下全是普通的 Markdown：程序、限制、你想要的輸出格式。哪裡都沒有程式碼，也不需要。

四種真正會出狀況的情形

接下來往哪走