繼上一篇〈Claude 工程師教你怎麼用 skills：怎們好好分類 skills〉我們認識了如何分類 skills，這一篇我們來學習打造 skills 需要注意的細節，未來在打造自己專用的 skills 時，也可以少踩一些雷。
Anthropic 最近也推出了 Skill Creator 的 plugin 幫助我們更快創造一個 skill。
Don't State the Obvious 說重點
用 Claude Code 開發到現在，想必大家都知道它有多聰明，甚至比我們更清楚專案的程式碼架構與預設通用的處理方式，所以當我們要撰寫一個新的 skills，「著重在那些能改變 AI 預設行為的具體規則、限制與偏好」，尤其是希望它避免一些的常見風格與行為模式。
如果曾經有用 agent 進行網站的 UI 設計，大概知道某些風格帶著一股濃濃的「AI 味」，像是藍紫色的漸層、特愛使用 emoji，這時候我們要寫一個前端設計用的 skill，大概會長這樣：
- 禁止使用 Inter font
- 避免 linear gradient（特別是 purple/blue）
- spacing 必須偏緊（不是 SaaS 寬鬆風格）
- button 不使用 rounded-fullBuild a Gotchas Section 紀錄注意事項
Agent 跟我們一樣會犯錯，那身為人類的我們是如何避免再次犯下同樣的錯誤呢？要嘛是痛到我們這輩子都不可能忘記，要嘛是紀錄下來，下次遇到類似的狀況時，可以回去看看之前是怎麼處理的。
同樣地，我們也可以將那些 agent 曾經犯下的錯誤記錄在 SKILL.md 裡的 Gotchas 區塊，每當我們開發過程中告訴 agent：「這邊你做錯了，應該怎樣怎樣怎樣」，也可以順手把這些紀錄回 SKILL.md，擴充 agent 對於這些情境的判斷與處理能力。
Use the File System & Progressive Disclosure 善用檔案系統結構並漸進式提供資訊
前一篇文章我們有提到，許多人對於 skills 最大的誤解之一是「把它當作是單純的 markdown 檔案」，但其實 skills 的內容可以包含 assets、scripts 等多種類型的檔案，所以與其一次把所有資訊塞在 SKILL.md，讓 agent 抓不著重點，更好的做法是在 SKILL.md 說明這個 skill 的結構與使用方式，並在對應的情境去閱讀指定的檔案。
舉例來說，我們可以將「API 的函式定義、參數說明、用法範例」等細項都放在 reference/api.md 中，並在 SKILL.md 告知 agent 若果需要查看 API 的詳細資訊，可以閱讀 reference/api.md，避免 agent 在一開始就過多的資訊干擾，稀釋了本來最該關注的任務。
# Skill 的參考架構
playwright-verifier/
│
├── SKILL.md ← # 入口（最重要）
│
├── references/ ← # 按需讀取（Progressive Disclosure）
│ ├── api.md
│ ├── selectors.md
│ └── assertions.md
│
├── scripts/ ← # 可執行工具（Verification 核心）
│ ├── run-test.ts
│ ├── login-flow.ts
│ └── checkout-flow.ts
│
├── assets/ ← # 模板（Claude 可直接 copy）
│ ├──test-template.ts
│ └── report-template.md可以注意上面的範例中，assets 裡面存放了「模板」類型的檔案，這些檔案可以讓 agent 依照我們期望的格式進行「照抄」，確保文件內容維持一致性。
Avoid Railroading Claude 避免過度規範
剛開始在學習使用 agent 時，我們時有耳聞「應該清楚地告訴 agent 每一步該怎麼做」，然而這種「步驟式」的說明現在反而對於 agent 來說是一把雙面刃，好處是「agent 基本上會照著指示實作」，壞處卻是「agent 會因為這些過於明確的指示，而無法依照多變的情境進行不同的處理」。
Agent 現在聰明的可以，我們只要給予必要的資訊，然後提供足夠的操作彈性，讓 agent 自動判斷該該種情境對應的處理方式。
以 Git 操作的 skill 為例：
過度規範的寫法
- 執行
git log查找 commit - 執行
git cherry-pick <hash> - 如果有衝突，執行
git status查看狀況 - 打開並查看每個衝突的檔案
- 針對每個衝突，選擇保留版本、修改內容或跳過
（寫完每個步驟）
合適的寫法
- 在乾淨的分支上進行 cherry-pick 並處理衝突
- 請確保原始目的與邏輯，如果無法安全合併，請說明原因
Think through the Setup 思考所需的前置資訊
如果我們要寫一個「天氣資訊」相關的 skill，你覺得 agent 在使用這個 skill 前，應該要先向我們確認哪些資訊，才能有效地回答呢？
至少 agent 需要知道「城市」、「日期」這兩件事，才能進一步去查詢並提供對我們有用的天氣資訊吧！
因此有些 skill 在 agent 使用前，會需要從指定的 config 檔案中查看是否有相關設定，這些必要的設定會建議存放在 skill 底下的 config.json 中。
如果沒有的話，則可以指示 agent 使用 AskUserQuestion 工具，向使用者詢問資訊，再繼續進行操作。
The Description Field Is For the Model 描述觸發條件
在寫 SKILL.md 時，我們會以為 description 是用來敘述這個 skill 的功能與使用方式，然而 description 的真正作用是用來「描述這個 skill 的觸發條件」，讓 agent 知道什麼時候該使用這個 skill。
因為當 Claude Code 開始一個新的對話 session 時，它會先載入所有可用的 skills 以及對應的 description，如果使用者在對話過程中，提到了符合 description 中所描述的條件，agent 就會自動觸發該 skill 來完成對應的任務。
Memory & Storing Data 給予記憶能力
受限於上下文（context）長度限制，通常每當我們跟 Claude Code 進行一段對話並一些任務後，要不就使用 /compact 來壓縮與總結先前的對話內容，要不就是用 /new 來開啟一輪新的對話 session，無論哪種方式都會導致先前對話內容的遺失，進而影響到後面的任務執行。
針對那些需要「前情提要」的 skills，我們可以透過 .log 或是 .json 來存儲對話過程中所產生的資料摘要，如果有必要，甚至可以使用 SQLite 資料庫來更有系統地儲存資料。
官方也有提醒，有時候存放在 skill 底下的 data 可能會因為「升級 skill」時被刪除，所以建議存在 ${CLAUDE_PLUGIN_DATA} 所指向的路徑，確保資料不會因為升級而遺失。
${CLAUDE_PLUGIN_DATA}是對應每個 plugin 所提供存放 data 的路徑，例如 plugin 的名稱叫作formatter@my-marketplace，那${CLAUDE_PLUGIN_DATA}則會對應到~/.claude/plugins/data/formatter-my-marketplace。詳細的轉換規則可參考 Plugins reference - Persistent data directory。
Store Scripts & Generate Code 提供可重用的函式
前面有稍稍提到，我們可以在 asset 中存放樣板文件，讓 agent 根據規範產出風格一致的文件，省去 agent 每次從零做起的時間，更可以減少 token 的消耗！
依循這個理念，我們也可以先在 skills 定義好一些常用的函式（helper functions），讓 agent 可以直接在對應情境調用指定的函式。
Agent 除了能調用這些函式，甚至可以自行將這些函式進行排列組合，來完成更複雜的任務。
On Demand Hooks 特定需求功能
偶爾會聽到網路上有些人抱怨「AI 把我的東西全部刪掉了」，這到底是 AI 的反撲還是我們給予 AI 過大的權限？又或者是我們描述地不夠清楚，導致 AI 會錯意，才發生了這樣的慘劇呢？
無論是哪種情況，說穿了，我們想要的就是特定狀況下不要「刪除檔案」或是「做出毀滅性的操作」。
舉例來說，我們可以定義一個名為 /careful 的 skill：
blocks rm -rf, DROP TABLE, force-push, kubectl delete via PreToolUse matcher on Bash.一旦我們使用在對話過程中使用了 /careful，agent 在當前的 session 便會遵循的這個 skill 所描述的行為，避免進行一些可能導致破壞的操作。
要注意的是，這些指令通常有適合的使用時機，如果在不當的時機使用，像是需要進行一些不必要的檔案刪除時，就會因為 /careful 過度限制而導致無法正常完成任務。
對於新手工程師而言，使用現成的 skills 像是一把雙面刃，誠然 skills 賦予 agent 更強大的能力，但也剝奪了我們在手動操作中會學習的經驗，以及對應各種情境應該要使用的 debug 方法。
在這個越來越少「純手工寫程式」的 AI 世代，我們至少可以看看別人是怎麼寫 skills，然後按照自己的需求、知識，改寫出符合自己風格的 skills，奪回一些自主思考的能力。