就算你打算自己寫，也先從別人的開始

先安裝一個的三個理由。 不需要寫程式 ——一個 Skill 就是一個裡面裝著 SKILL.md 指示檔案的資料夾；作者已經打包好了，你只要提供來源、按 Install 就好。 你可以先試用，不用先投入時間 ——大概三分鐘，比花一小時研究範例快多了。而且 你會拿到一個能用的範例：打開安裝好的 SKILL.md ，看看別人是怎麼寫的。

Skill 是 Pi Agent 運作方式的核心，不是可有可無的東西。同一個模型——比如 GLM-4.6——裝了 Skill，結果可能有很大的差異。裝了 home-assistant-best-practices 之後，模型可能會告訴你，某個特定的自動化用 helper 比用 template sensor 好。沒裝的話，它就會回到自己那套可能已經過時的習慣。熟悉的比喻是 HACS：內建的東西能用，而社群有時候會提供更適合你需求的東西。

打開 Settings ，選 Skills 分頁——頂部五個分頁中的第三個，在 Models 跟 Sub-agents 之間。

Skill 住在哪裡Settings 的 Skills 分頁，什麼都還沒裝之前的樣子。

• No skills found 填滿了左欄。這一欄是已安裝的清單，所以空的正是一開始正確的狀態。
• + Add skill 在那一欄的最下面——這個畫面上唯一的控制項，也是每一次安裝的起點。
• Select a skill 是右側面板的預留文字，之後會被 Skill 的細節，或 Add skill 表單填滿。

四種命名套件的方式，加一種會被拒絕的方式

搜尋找到的是有人列在目錄裡的東西。其他所有的——沒列出的倉庫、npm 套件、你主機上已經有的資料夾——都是靠 套件規格來安裝，也就是面板前台代理的那個指令的參數： pi install <package-spec>。Pi Agent 建立在 @earendil-works/pi-coding-agent之上，它的命令列介面是 pi。套件規格有明確定義的語法；一個你認得出來的倉庫名稱不算數。有四種來源類型是合法的。

還有一條容易漏掉的規則： 引用會被釘住。 @v1 一直指的都是 v1；一次更新只會重新整理那個版本的內容，不會把你帶到 v2。要換版本引用得重新安裝，下面會講。

這裡沒有預設一定是 GitHub。換掉主機—— git:gitlab.com/user/repo、 git:codeberg.org/user/repo，或你自己的伺服器 git:git.your-domain.tw/user/repo。

四種寫法最後都走到同一個發現步驟。Pi 會掃描三個目錄，找裡面有 SKILL.md的資料夾： ~/.pi/agent/npm/、 ~/.pi/agent/git/，且 ~/.pi/agent/skills/。最後那個是一個符號連結，指向 /data/pi-agent/skills/，手寫的 Skill 放這裡——不要在這裡找已安裝的 Git 套件。因為 $HOME 被釘在附加元件的資料磁區裡，面板跟命令列看到的是同一批 Skill，Home Assistant 的 snapshot 也會把整個收藏帶回來： skills/、 npm/、 git/，以及 ~/.pi/agent/settings.json。

一個來源通不通得過，主要看驗證方式。

安裝一個真實的 Skill，再證明 agent 看得到它

按 + Add skill ，右側面板就會填滿。

Add skill一個搜尋欄、一個範圍切換鈕、一個連到目錄的連結。

• 那個 欄位要的是關鍵字，不是網址。它的提示文字寫著 e.g. react, testing, deploy，藍色的 Search 按鈕會查詢 skills.sh 目錄。
• global / project 決定哪個設定檔會記錄這次安裝。Global 寫進 ~/.pi/agent/settings.json，project 寫進 .pi/settings.json ，就在你的工作目錄旁邊。箭頭標的是你選的範圍的路徑， ~/.pi/agent/skills/。除非你需要一個只給特定專案用的 Skill，不然就留在 global。
• skills.sh 是最後一行的連結——社群整理的目錄，是最接近官方 Skill 商店的東西。

1. 步驟 1

   搜尋它，或用規格安裝

   點 + Add skill，輸入 mattpocock ，點 Search。這篇教學用的是 mattpocock/skills：在家用不太到，但安裝起來很穩定。面板呼叫的是 /api/skills/search；符合的卡片會各自帶著自己的 Install 按鈕回來。如果目錄裡沒有你要的，打開連到附加元件的終端機，跑下面其中一個：

   pi install git:github.com/mattpocock/skills

   pi install https://github.com/mattpocock/skills

   pi install git:github.com/mattpocock/skills@main

   第三種寫法釘住一個標籤或 commit。不要輸入單獨的 mattpocock/skills。

2. 步驟 2

   點 Install，然後不要管它

   按鈕顯示 Installing… ，這段期間它在運作。背後面板送出的是 /api/skills/install ，用 {cwd, package, scope} ，後端跑的是 pi install。通常 5-30 秒，看倉庫大小跟你的網路。不要取消或重新整理頁面。最後會跳出一個 Package installed. 提示。

3. 步驟 3

   檢查出現的項目

   新的 Skill 會出現在左欄。點它：面板上會有一個啟用／停用開關、 Check Updates、 Remove，且 Installed Path ——在 ~/.pi/agent/npm/ ，給 npm 套件用， ~/.pi/agent/git/<host>/<path>/ ，給 Git 套件用。

4. 步驟 4

   重新載入 session，不是重新整理頁面

   Reload Session 通常在右上角；點它應該會看到 Session reloaded. 開新 session 也行。F5 不行——system prompt 是 session 開始時組出來的，中途不會重讀，這也是新裝的 Skill 看起來憑空消失最常見的原因。

5. 步驟 5

   在 system prompt 裡找到它，用一次看看

   打開唯讀的 System Prompt 面板，捲到 <available_skills> 區塊；你的 Skill 名字應該在裡面。這證明了 Pi 找到它——但不證明 agent 會用得好。所以也試著在測試請求裡點名它：「請用 Skill name 幫我做某件事。」如果回覆有反應、正確的工具也出現了，就代表能用。

6. 步驟 6

   在依賴它之前先讀懂它的 SKILL.md

   SKILL.md 是 Pi 會讀的檔案，不是 README.md：它裝著 name、 description 跟 allowed-tools 這些 frontmatter 欄位，應該會寫清楚什麼會觸發它、它需要哪些工具、期望哪些環境變數。照著 Installed Path 找過去—— /data/pi-agent/home/.pi/agent/git/<host>/<user>/<repo>/SKILL.md 給 Git 套件用，對應的 …/npm/… 路徑給 npm 套件用。花五分鐘讀，比花半小時瞎猜划算得多。

每個已安裝的 Skill 都會釘在每次對話的最前面，不管相不相關，所以用不到的就移除。有兩種方式，對應兩種情況。

從面板，大概 99% 的情況都對：選那個 Skill，點 Remove，確認。後端跑的是 pi remove <spec>，從 settings.json，刪除 ~/.pi/agent/git/… 或 ~/.pi/agent/npm/…，並顯示 Package removed. 提示。它不會留下過時的設定，也不會刪錯路徑。

從連到附加元件的終端機，適用於面板用不了、套件壞到列不出來，或你要一次清好幾個的情況。在使用任何主機層級的 exec 指令之前，先確認你部署環境專屬的容器名稱，接著：

一個資料夾、一個檔案，不寫程式

公開發布的 Skill 處理的是通用需求——管理檔案、建網站。它們對你家一無所知。你自己的 Skill 才是你把重複又具體的工作交出去的方式：拍冰箱照片拿回一份盤點清單，或者從你放進資料夾的說明書裡回答洗碗機的錯誤代碼。

整個結構就是一個資料夾、一個檔案：

裡面裝三個元素，只有兩個是必要的。

檔名要精確： SKILL 大寫， .md 小寫。大小寫寫錯，Pi 就找不到。Markdown 就是你在 GitHub 跟 Obsidian 上看過的那種純文字格式—— # 做標題， - 做條列項目——就算你沒用過，agent 照樣看得懂普通的段落。

關於 frontmatter 的兩個要點。 name 是識別碼：小寫字母加連字號，例如 fridge-check，最好跟資料夾名稱一致。非 ASCII 的名稱可能能用，但用 ASCII 能避開跨作業系統的路徑編碼問題。 description 最重要——agent 靠它來判斷這個 Skill 到底適不適用。

這是完整的檔案內容。複製進 SKILL.md的資料夾：

把 輸出範例 這個區塊當成範本，下一次重新填寫：名字、描述、什麼時候用、步驟、安全事項、輸出格式。

接下來把資料夾放到主機上。 比較快的路 ——大概兩分鐘——是用 scp，或 FileZilla、Cyberduck 這類 SFTP 客戶端，傳到 /data/pi-agent/skills/。把主機位址換成你自己的：

比較慢的路 是用 GitHub，換來版本歷史跟分享的能力：

接著把它裝回來：在面板裡點 Add from URL，貼上倉庫網址，點 Install ——或用套件規格， pi install https://github.com/your-account/fridge-check。兩條路最後都會把資料夾放在 /data/pi-agent/skills/。改動的時候，先在本機用 scp 反覆調整，等 Skill 穩定了再推上 GitHub。

最後開一個新 session，檢查 <available_skills> 有沒有 fridge-check，再附上一張你冰箱的照片——先看過照片有沒有隱私內容。回覆應該依序描述看得到的東西、標出該檢查的項目、建議晚餐、列出接下來要檢查什麼，而且不能有沒根據的安全宣稱。

三件決定 agent 到底會不會用它的事

裝了幾個之後，寫得好不好幾乎決定了一切。三個原則做了大部分的工作。

禁止事項是大家最容易漏掉的部分，而它們很重要，因為這些系統本來就很急著幫忙。不把界線講清楚，一份盤點清單就可能漂移成編造出來的營養報告，或關於細菌跟疾病的宣稱。直白的指示——「不要診斷」、「不要單憑一張圖就推斷安不安全」——能讓輸出維持有用，並保持適當的限制。但也不要矯枉過正：滿篇的「必須」跟「絕對不要」會讓回覆聽起來很像照本宣科，所以真的該由判斷力決定的地方，用「優先」、「通常」或「避免」，只有真正的禁止事項才寫得堅定。

flowchart TD
  A["agent 沒理我的 Skill"] --> B{"Is it listed in the
available_skills block?"}
  B -->|"no"| C["Pi 從沒載入過它。
檢查資料夾位置
跟 frontmatter"]
  B -->|"yes"| D{"Does the description name
the words you actually used?"}
  D -->|"no"| E["用具體的觸發條件
重寫 description"]
  D -->|"yes"| F["換一個指令遵循能力更強的
模型試試，並且讀它的
工具呼叫，不只讀回覆"]

還有一個習慣：讓每個 Skill 只做一件事。單一用途的描述更容易對上、衝突更容易診斷，而且一次改動影響的範圍更小——冰箱盤點、晚餐建議、採買規劃拆成三個 Skill，會比合成一個好用，就算它們彼此會互相參照也一樣。

同一個範本，重複七次

下面每一項填的都是同樣的空格：要外包出去的重複工作、agent 必須遵守的規則，以及旁邊核准的參考素材 SKILL.md。七個構想，包括你已經做好的那個。

如果你的某個 Skill 在你家以外也安全又有用，就發布到一個公開的 GitHub 倉庫，讓其他人在安裝前能先讀過。發布前先做四件事。

1. 步驟 1

   確認倉庫真的是公開的

   在 GitHub 打開倉庫，去 Settings ，捲到 Danger Zone 確認它的可見度。私有倉庫沒有驗證是抓不到的，所以別人的安裝一定會失敗。

2. 步驟 2

   第一次推送之前，先去掉任何私密內容

   憑證、個人資訊、內部主機名稱、entity 名稱、路徑、家庭細節。一旦推上公開倉庫就會留在歷史紀錄裡，所以這件事要在推送之前做，不是之後。

3. 步驟 3

   分享一個大家真的貼得上去的規格

   不要叫任何人輸入 your-account/fridge-check ——Pi 會拒絕單獨的簡寫。給他們 git: 這種格式，或完整的 https://github.com/… 網址。

4. 步驟 4

   加一份給人看的 README.md

   解釋這個 Skill 做什麼、怎麼用，還有一段範例對話長什麼樣，讓人在安裝前就能判斷合不合用。 SKILL.md 是寫給 agent 看的； README.md 是給人看的。

你最可能撞上的失敗情況

先從機械性的開始。

剩下的部分

接下來往哪走