skill-forge

Skill Forge

鐵律：Skill 中的每一行內容都必須有其 Token 成本的合理性。如果無法讓模型的輸出變得更好、更一致或更可靠，就直接刪除它。

什麼是 Skill

Skill 是 Claude 的「入職指南」——將它從通用 Agent 轉變為具備程序化知識、領域專業與打包工具的專門 Agent。

skill-name/
├── SKILL.md           # 必填：工作流程 + 指示（<500 行）
├── scripts/           # 選填：確定性、可重複執行的操作
├── references/        # 選填：按需載入至 Context 中
└── assets/            # 選填：用於輸出結果，絕不載入至 Context 中

預設前提：Claude 本身已經非常聰明。 只需新增 Claude 尚不知道的內容。質疑每一段落：「這真的符合 Token 成本嗎？」

工作流程（Workflow）

複製此檢查清單，並在完成各項目時勾選：

Skill Forge 進度：

- [ ] Step 1: 理解 Skill ⚠️ 必填
  - [ ] 1.1 理清目的與具體使用場景
  - [ ] 1.2 收集 3 個以上的具體使用範例
  - [ ] 1.3 識別觸發場景與關鍵字
- [ ] Step 2: 規劃架構
  - [ ] 2.1 識別可複用資源（scripts、references、assets）
  - [ ] 2.2 設計漸進式載入策略
  - [ ] 2.3 設計參數系統（若適用）
- [ ] Step 3: 初始化 ⛔ 阻擋性步驟（若 Skill 已存在則跳過）
  - [ ] 執行 init_skill.py
- [ ] Step 4: 撰寫 Description
  - [ ] 載入 references/description-guide.md
  - [ ] 套用關鍵字地毯式覆蓋（Keyword Bombing）技巧
- [ ] Step 5: 撰寫 SKILL.md 主體
  - [ ] 5.1 設定鐵律（Iron Law）
  - [ ] 5.2 設計工作流程檢查清單
  - [ ] 5.3 新增確認關卡（Confirmation Gates）
  - [ ] 5.4 新增參數系統（若適用）
  - [ ] 5.5 套用撰寫技巧
  - [ ] 5.6 新增反模式（Anti-Patterns）清單
  - [ ] 5.7 新增交付前檢查清單
- [ ] Step 6: 建置資源
  - [ ] 6.1 實作並測試指令稿（Scripts）
  - [ ] 6.2 撰寫參考文件（References）
  - [ ] 6.3 準備資產檔案（Assets）
- [ ] Step 7: 審查 ⚠️ 必填
  - [ ] 執行交付前檢查清單（Step 9）
  - [ ] 向使用者展示摘要以供確認
- [ ] Step 8: 打包
  - [ ] 執行 package_skill.py
- [ ] Step 9: 根據實際使用情況迭代

Step 1: 理解 Skill ⚠️ 必填

捫心自問：

• 這個 Skill 解決了什麼 Claude 單靠自己無法妥善處理的具體問題？
• 使用者字面上會輸入什麼來觸發這個 Skill？
• 有哪些 3-5 個包含真實輸入與預期輸出的具體使用範例？

若不清楚，請詢問使用者（不要一次問所有問題——從最關鍵的開始）：

• 「你能給我 3 個使用這個 Skill 的具體範例嗎？」
• 「字面上你會說什麼來觸發它？」
• 「好的輸出結果看起來像什麼？」

在拿到至少 3 個具體範例前，切勿繼續下一步。

Step 2: 規劃架構

針對每個具體範例，思考：

1. 哪些操作是確定性且可重複執行的？ → scripts/
2. Claude 在特定步驟需要哪些領域知識？ → references/
3. 哪些檔案僅用於輸出，而不參與推理？ → assets/

關鍵限制：

• SKILL.md 必須保持在 500 行以內 — 其他內容全部放入 references/
• 參考文件依領域組織，只允許一層資料夾巢狀結構
• 載入 references/architecture-guide.md 以了解漸進式載入模式與組織策略

Step 3: 初始化 ⛔ 阻擋性步驟

若是在修訂既有 Skill，請跳過此步驟。否則請執行：

python3 scripts/init_skill.py <skill-name> --path <output-directory>

此指令稿會建立包含鐵律占位符、工作流程檢查清單與正確目錄結構的範本。

Step 4: 撰寫 Description

這是 Skill 中最容易被低估的部分。Description 決定了：

1. Skill 是否會自動觸發
2. 使用者能否透過搜尋找到它

載入 references/description-guide.md 以學習關鍵字地毯式覆蓋技巧及好/壞範例。

關鍵規則：絕不在 SKILL.md 主體中放「何時使用（When to Use）」的資訊。主體是在觸發後才載入 — 那時就太晚了。

Step 5: 撰寫 SKILL.md 主體

按需載入各子步驟的參考文件：

5.1 設定鐵律（Iron Law）

思考：「模型在使用這個 Skill 時，最容易犯下的單一最大錯誤是什麼？」
撰寫一條能阻止該錯誤的規則。將其放在 SKILL.md 的最上方，緊跟在 Frontmatter 之後。

→ 載入 references/writing-techniques.md 以了解鐵律模式與紅旗警告訊號。

5.2 設計工作流程檢查清單

建立可追蹤的檢查清單，包含：

• ⚠️ 必填：絕對不可跳過的步驟
• ⛔ 阻擋性：前置條件步驟
• 複雜步驟的子步驟巢狀結構
• (條件性)：取決於先前選擇的步驟

→ 載入 references/workflow-patterns.md 以取得檢查清單模式與範例。

5.3 新增確認關卡（Confirmation Gates）

強制模型在執行以下操作前停下來詢問使用者：

• 破壞性操作（刪除、覆寫、修改）
• 成本昂貴的生成操作
• 根據分析結果套用變更

→ 載入 references/workflow-patterns.md 以取得確認關卡模式。

5.4 新增參數系統（若適用）

如果 Skill 適合支援 --quick、--style、--regenerate N 等 Flag：

→ 載入 references/parameter-system.md 以取得 $ARGUMENTS、Flag、argument-hint 及部分執行模式。

5.5 套用撰寫技巧

能大幅提升輸出品質的三種技巧：

1. 提問式指示（Question-style instructions）：提供明確問題，而非含糊的指令
2. 反模式文件（Anti-pattern documentation）：列出不該做的事
3. 鐵律 + 紅旗警告（Iron Law + Red Flags）：防止模型走捷徑偷懶

→ 載入 references/writing-techniques.md 以查看這三種技巧的範例。

5.6 新增反模式（Anti-Patterns）清單

思考：「Claude 對於這項任務的偷懶預設行為會是什麼樣子？」然後明確禁止它。

→ 載入 references/writing-techniques.md 以查看反模式範例。

5.7 新增交付前檢查清單

新增具體且可驗證的檢查點。每個項目都必須足夠具體，讓模型只需檢查輸出結果即可驗證。不是「確保品質良好」，而是「沒有殘留占位符文字（TODO、FIXME、xxx）」。

→ 載入 references/output-patterns.md 以取得檢查清單模式與基於優先級的輸出模式。

撰寫原則

• 精簡：僅新增 Claude 尚不知道的內容
• 祈使句型：「分析輸入」而非「你應該分析輸入」
• 自由度應與脆弱度相匹配：窄橋 → 具體防護欄；開闊空地 → 多條路線
  • 高自由度（文字）：多種有效方法
  • 中自由度（虛擬碼/參數）：推薦模式，允許少許變異
  • 低自由度（特定指令稿）：易碎操作，一致性至關重要

Step 6: 建置資源

指令稿（Scripts）

• 封裝確定性、可重複執行的操作
• 指令稿可在不載入至 Context 的情況下執行 — 節省大量 Token
• 打包前測試每一個指令稿
• 在 SKILL.md 中，僅記錄指令與引數，不要附上原始碼

參考文件（References）

• 依領域組織，而非依類型組織
• 只允許一層資料夾巢狀結構
• SKILL.md 中引用每個檔案時，需附帶明確的「何時載入」指示
• 大型檔案（>100 行）頂部應附有目錄（Table of Contents）

資產檔案（Assets）

• 用於輸出結果的範本、圖片、字型
• 不會載入至 Context，僅透過路徑引用

→ 載入 references/architecture-guide.md 以查看詳細模式。

Step 7: 審查 ⚠️ 必填

在打包前，向使用者展示 Skill 摘要並進行確認。

交付前檢查清單

結構

• [ ] SKILL.md 控制在 500 行以內
• [ ] Frontmatter 僅包含 name 與 description（以及選填的 allowed-tools、license、metadata）
• [ ] Description 包含觸發關鍵字與使用場景
• [ ] 無 README.md、CHANGELOG.md 或其他不必要的檔案
• [ ] 無初始化留下的範例/占位符檔案

品質

• [ ] 頂部設有鐵律或核心限制
• [ ] 擁有包含 ⚠️/⛔ 標記的可追蹤工作流程檢查清單
• [ ] 破壞性/高成本生成操作前設有確認關卡
• [ ] 使用提問式指示，而非含糊指令
• [ ] 列出反模式（不該做的事）
• [ ] 參考文件為漸進式載入，而非一次性全部載入

資源

• [ ] 指令稿已測試且可執行
• [ ] 參考文件按領域組織，深至一層
• [ ] 大型參考文件附有目錄
• [ ] 資產檔案用於輸出結果，未載入至 Context

應避免的反模式

• 將所有內容塞進單一龐大的 SKILL.md（>500 行）
• 含糊的 Description，例如「用於 X 的工具」
• 缺乏工作流程 — 讓模型自由發揮
• 缺乏確認關卡 — 模型未受檢查即一路執行至完成
• 含糊的指示，例如「確保品質良好」，而非具體檢查點
• 包含 README.md、INSTALLATION_GUIDE.md 或其他文件檔案
• 將「何時使用」資訊放在主體中而非 description 欄位

Step 8: 打包

python3 scripts/package_skill.py <path/to/skill-folder> [output-directory]

打包前會自動驗證。修復錯誤後重新執行。

Step 9: 迭代

實際使用後：

1. 觀察模型在哪裡遇到困難或表現不一致
2. 識別哪一個工作流程步驟需要改進
3. 新增更具體的指示、範例或反模式
4. 重新測試並重新打包