ito-skill

概覽

以訪談規則引導使用者釐清 skill 設計，產出高品質 SKILL.md 及必要子目錄，支援建立、編輯與 review 三種模式，在寫入前進行即時驗證與自我審查。

使用時機

• 使用者說「建立一個 skill」、「幫我寫一個 skill」、「新增 skill」
• 使用者說「改 [skill-name]」、「更新 [skill-name] 的觸發條件」、「修一下這個 skill」
• 使用者說「審查 [skill-name]」、「檢查 [skill-name] 的品質」
• 需要為重複性工作流程建立可重用的 agent 指引

不應使用的情況： 需要驗證既有 skill 效果的任務、需要執行 skill 所描述的任務本身。

核心流程

從使用者第一句話推斷模式，執行對應分支，完成後進行自我審查。

• 建立模式：含「建立 / 新增 / 寫一個」→ 進入全動態訪談（詳見「建立模式」）
• 編輯模式：含「改 / 更新 / 修 / edit」且可辨識既有 skill 名稱 → 讀取所有現有檔案後進入局部訪談（詳見「編輯模式」）
• review 模式：含「審查 / 檢查」且可辨識既有 skill 名稱 → 讀取所有現有檔案後進入審查流程（詳見「review 模式」）
• 不確定時：以一句話向使用者確認，不擅自決定

訪談規則

核心守則

1. 一回合只問一題，追問留至下一回合
2. 每個回答都是下一個問題的起點，找出隱含假設或潛在弱點後繼續，不因回答聽起來合理就放過
3. 前一決策解鎖新子問題時，先一句話說明依賴關係，再提問
4. 技術問題優先探索 codebase，取得結果後一句話複述並請使用者確認
5. 以簡潔且通順的文字提問，講重點，不堆砌專有名詞

問題類型

• 決策型（使用者需選方向）：說明情境、列出 2–4 個互斥選項、附上推薦與理由
• 現況確認型（了解既有狀態）：說明原因、列出可能情況，不附推薦
• 開放型（本質發散的背景問題）：說明為何需要開放回答，直接問，附上預期或假設

若能列出互斥選項，優先用決策型或現況確認型。只有問題本質發散時才用開放型。取得開放回答後，立即以決策型或現況確認型往下深挖。

建立模式

步驟 1：目錄衝突檢查

檢查 .claude/skills/<name>/ 是否已存在。若存在，中止並顯示既有 skill 的 description，提供三選一：

• A）覆蓋（git 版本控制負責備份）
• B）改名
• C）取消

步驟 2：動態訪談

依「訪談規則」逐一追問 skill 設計。預設假設 skill 設計存在模糊地帶：主動以邊界條件、反例或缺漏情境挑戰使用者的初步描述，而非只被動收集資訊。

1. name：1–64 字元、小寫字母 + 數字 + 單個 hyphen、不得連續 hyphen
2. description：描述功能 + 正向觸發 + 負面觸發，若超過 250 Unicode 字元則警示
3. 使用時機：正向觸發條件 + 不應使用情況
4. 核心流程步驟：時序明確，有決策分支時須逐一說明

收斂條件（目標導向）： 四個必要欄位全部收集完畢且邊界條件釐清後，主動宣告「資訊足夠，可以收斂」，未解問題列入待決清單。

步驟 3：推斷子目錄需求

根據訪談內容推斷是否需要子目錄：

判斷條件	建議放置
易錯或重複性工作（解析、查詢、格式轉換）	scripts/
大型 schema、API 速查表、領域知識	references/
固定輸出格式、模板、靜態檔案	assets/

同時判斷是否納入選用段落（警訊 / 錯誤處理 / 驗證 / 延伸參考）：流程複雜、有明確邊界條件或外部依賴時納入；簡單線性流程時省略。

步驟 4：預覽與確認

填入 assets/skill-template.md → 輸出完整預覽。

若推斷需要子目錄或選用段落，附上建議清單與納入理由，請使用者一併確認再進入步驟 5。

步驟 5：寫入

使用者批准後：

1. 建立 .claude/skills/<name>/SKILL.md
2. 依批准的子目錄清單建立對應目錄與初始檔案
3. 執行自我審查（見「自我審查」）

編輯模式

步驟 1：讀取現有檔案

讀取 .claude/skills/<name>/ 下的全部檔案：SKILL.md、references/*、assets/*、scripts/*。

步驟 2：局部訪談

若問題可藉由讀取現有 skill 檔案取得答案，優先讀取，確認結果後向使用者複述並請求確認，避免詢問使用者已可自行確認的技術細節。

從使用者第一句話的意圖直接切入，只針對變更點和其直接依賴分支依照「訪談規則」追問，不重跑無關欄位。

名稱變更時，視為重新命名：確認 references/、assets/、scripts/ 內的相對路徑不會失效，必要時同步更新路徑引用。

步驟 3：差異預覽與確認

條列各項變更摘要，必要時附上原文片段，多檔時逐檔列出，請使用者確認後再寫入。

步驟 4：寫入與自我審查

使用者批准後執行 Edit，再執行自我審查。

review 模式

步驟 1：讀取 skill 目錄

讀取 .claude/skills/<name>/ 下的全部檔案：SKILL.md、references/*、assets/*、scripts/*。

步驟 2：審查

1. 執行 python3 .claude/skills/ito-skill/scripts/validate-metadata.py --name "[name]" --description "[description]" 驗證 frontmatter；若失敗記錄為問題清單第一項
2. 讀取 references/review-rubric.md，依各區塊逐一審查所有檔案

步驟 3：回報問題

條列所有發現的問題，每則格式如下：

• 問題：說明問題內容
• 位置：指出所在檔案與段落
• 建議：提供具體修改方向

問題清單結尾詢問：「要全部修正，還是選擇部分項目？（請列出編號或說全部）」

步驟 4：選擇性修正

依使用者選擇的項目執行 Edit，修完後告知每項修正點。

自我審查

寫入後：

1. 執行 python3 .claude/skills/ito-skill/scripts/validate-metadata.py --name "[name]" --description "[description]" 驗證 frontmatter；若 stderr 回報錯誤，依指示修正後重跑直至 SUCCESS
2. 讀取 references/review-rubric.md，依各項標準重讀檔案；若發現問題則執行 Edit 修正，並告知使用者修正點

常見合理化藉口

合理化藉口	實際情況
「使用者說清楚了，不用再追問」	跳過追問會累積隱性假設，使 skill 在邊界條件失效
「一次問多題比較快」	多題並問讓使用者遺漏分支，破壞決策樹完整性
「這個 skill 很簡單，不需要預覽」	預覽是使用者確認輸出符合預期的唯一機會，不可省略
「子目錄之後再說」	訪談後才加子目錄會破壞 SKILL.md 的流程完整性
「直接寫就好，不用填模板」	模板確保段落結構與語言風格一致，跳過會讓輸出品質不穩定
「review 只需要看 SKILL.md 就夠了」	references/ 的 broken path 和 assets/ 的格式問題同樣影響 skill 品質

警訊

• 一回合出現兩個以上問題
• 決策型問題缺少推薦與理由
• 開放型問題沒有附預期或假設
• 全程未主動挑戰任何模糊描述或邊界條件
• 使用者回答超出選項範圍未經追問即繼續下一題
• 編輯模式中，跳過讀取現有 skill 檔案直接向使用者詢問技術細節
• review 模式中，未列完所有問題就直接 Edit

錯誤處理

• 若使用者說「先跳過這題」，記錄為待確認項目，訪談結束後列入預覽的待決清單
• 若使用者回答「不知道」，先以反推或反例切入引導（例如：「如果不加這個觸發條件，會誤觸什麼情況？」），若仍無法回答，記錄為待確認項目後繼續
• 若使用者回答超出選項範圍，須根據該回答追問，釐清其對 skill 設計的含義後再繼續

驗證

• 使用者確認預覽並批准寫入
• SKILL.md 已成功建立（或編輯後內容已更新）
• 自我審查無遺留問題，或問題已修正並告知使用者

語言規則

撰寫產出的 skill 時，以台灣繁體中文為主；英文僅在下列情況保留：

• 技術符號與路徑名稱（SKILL.md、references/、frontmatter、hook）
• 英文形式在台灣工程師日常語境中比中文更自然、更無歧義（如 progressive disclosure）

其餘術語優先找對應中文，若翻譯反而造成理解困難，保留英文並在首次出現時附上中文說明。

中文正文避免使用破折號（——）與分號（;），以逗號或句號替代。

延伸參考

• references/review-rubric.md：SKILL.md 品質評審標準，自我審查與 review 模式時讀取
• assets/skill-template.md：新 skill 的輸出模板，填寫預覽時讀取
• scripts/validate-metadata.py：驗證 frontmatter name/description 格式與語態，自我審查與 review 模式時執行