name: skill-crafter description: 建立高質量 Skill 的技能。當用戶說"建立技能""新建 Skill""把這個流程變成技能""做一個 XX 的 skill""幫我寫個技能"時觸發。不適用於使用已有技能執行任務——那是 use_skill 的工作。

Skill Crafter

建立、修改和最佳化 Skill。核心方法：四層骨架 + 四階段流程。

你的工作方式

1. Phase 1：需求理解 — 吃透使用者已說的，推斷能補全的，只追問真正缺失的
2. Phase 2：編寫技能 — 用 init_skill.py 初始化，按 Phase 1→2 對映規則填充四層骨架
3. Phase 3：質量驗證 + 註冊 — 逐層檢查，修復問題，上傳註冊
4. Phase 4：迭代改進 — 根據使用症狀診斷問題，精確修復，沉澱踩坑經驗

修改已有技能時：定位 → 讀取 → 用 file_edit 精確修改 → 迴歸檢查 → 重新註冊。

Phase 1：需求理解

使用者開口時已經帶了大量資訊。先吃透已說的，再推斷能補全的，只追問真正缺失的。

資訊獲取優先順序

1. 對話歷史優先：使用者剛完成一個任務說"把剛才的做成技能"，從對話歷史提取工作流——用什麼工具、執行什麼步驟、使用者做了什麼修正、輸入輸出是什麼。這種情況下通常不需要追問。
2. 使用者描述中提取：使用者說"幫我建立公眾號長文的 skill，我是 AI 行業的"，已經包含技能目標、領域、輸出形式。
3. 合理推斷：從技能型別可以推斷大部分細節，把推斷整理好一次性讓使用者確認。

只問使用者需求

聚焦於"這個技能要幫你做什麼"。觸發短語怎麼寫、description 怎麼組織——這些是你的工作，不要讓使用者操心。

一輪對齊

最多追問一輪。整理你對技能的理解為簡潔摘要，附上少量需要使用者決定的選項，一次性發出。使用者確認後直接進入 Phase 2。

Phase 2：編寫技能

初始化

python3 /sandbox/workspace/skills/skill-crafter/scripts/init_skill.py {name}

指令碼會生成目錄骨架和四層結構的 SKILL.md 模板。根據需要替換或刪除示例檔案，刪除不需要的空目錄。

Phase 1→2 對映

需求理解產出的每條資訊，對應四層骨架的特定位置。不要猜，按對映表填充：

詳細對映規則見 references/phase-mapping.md

核心對映：

完整案例見 references/example-complete.md——一個從第一行到最後一行用四層骨架寫好的真實 Skill。

四層骨架

SKILL.md 由四層組成，Agent 讀取時分層遞進。每一層寫錯了，後面的效果就會打折。

第一層：頭部（description）——觸發器，不是摘要

description 決定 Agent 會不會選用這個 Skill。絕大多數 Skill 在這一步就被跳過了。

寫法：

1. 第一句說這個 Skill 做什麼
2. 中間寫 Use when user asks to + 使用者可能說的觸發短語（多種表達方式）
3. 最後說不適用的邊界

正確示例：

description: 獲取並轉換微信公眾號文章為Markdown的封裝Skill。
  Use when user asks to 抓取微信公眾號文章、抓微信、
  下載公眾號文章、URL轉Markdown、微信文章儲存.
  不適用於通用網頁抓取或非微信內容.

錯誤示例：

description: WeSpy的封裝，支援微信公眾號文章抓取和專輯批次下載。

問題：缺少觸發詞。使用者說"幫我抓一下這篇微信文章"，Agent 看著這個 description 不確定該不該用——因為沒有"抓取微信文章"這種使用者會說的表達。

關鍵原則： Use when user asks to 不是註釋，是給 Agent 的匹配訊號。它後面的詞就是觸發條件。

第二層：概述——畫邊界，不畫地圖

概述 = 一句話定位 + 功能範圍列表。只列"能做什麼"，不寫"怎麼做"。

正確示例：

## 概述

封裝 WeSpy 的完整能力。

### 功能範圍

- 單篇文章抓取（微信公眾號 / 通用網頁 / 掘金）
- 微信專輯文章列表獲取
- 微信專輯批次下載
- 多格式輸出（Markdown / HTML / JSON）

錯誤示例：

## 功能範圍
- 單篇文章抓取，使用 python3 scripts/wespy_cli.py URL 命令
- 微信專輯文章列表獲取，加上 --album-only 引數

問題：把操作細節塞進功能範圍。Agent 還沒決定要不要用你呢，你就讓它看命令列了？"能做什麼"歸概述，"怎麼做"歸操作指南。

第三層：操作指南——給場景，不只是給命令

Agent 在這一層逗留時間最長——這是它真正執行任務時參照的內容。

按場景給示例，不要按引數給說明。

正確示例：

## 使用

指令碼位置：scripts/wespy_cli.py

# 單篇文章抓取
python3 scripts/wespy_cli.py "https://mp.weixin.qq.com/s/xxxxx"

# 專輯批次下載（下載前20篇）
python3 scripts/wespy_cli.py "https://mp.weixin.qq.com/mp/appmsgalbum?..." --max-articles 20

# 僅獲取專輯文章列表（不下載）
python3 scripts/wespy_cli.py "URL" --album-only

Agent 直接對號入座——使用者需求匹配哪個場景，就用哪條命令。不需要自己拼。

錯誤示例：

## 引數說明
- URL：文章或專輯的連結
- --album-only：僅獲取專輯列表
- --max-articles N：批次下載時指定數量

命令：python3 scripts/wespy_cli.py [URL] [OPTIONS]

問題：Agent 看到通用模板，得自己拼命令。每多一步判斷，就多一次出錯。

第四層：補充說明——堵死岔路口

Agent 執行中遇到問題來查這一層。覆蓋所有"可能走錯"的判斷點。

需要覆蓋的典型場景：

• 依賴不存在怎麼辦（自動安裝？報錯？降級方案？）
• 輸入格式不對怎麼辦
• 輸出目錄不存在怎麼辦
• 網路超時怎麼辦
• 同名檔案已存在，覆蓋還是跳過

每一個踩過的坑，都寫進補充說明。 Skill 會隨著使用越來越"聰明"，就是因為踩過的坑都沉澱在這裡了。

結構模式

四層骨架是組織原則，結構模式是內容模式。根據技能用途選擇：

1. 流程型（有明確步驟的工作流） - 結構：概述 → Phase 1 → Phase 2 → ... → 多輪修改 - 示例：報告生成、資料分析

2. 任務型（多種獨立操作，按意圖路由） - 結構：概述 → 決策表 → 操作 1 → 操作 2 → ... - 示例：知識庫管理、檔案操作

3. 規範型（標準/規範/指南） - 結構：概述 → 規範細則 → 檢查清單 - 示例：品牌寫作規範、程式碼規範

4. 能力集型（多個關聯功能的整合） - 結構：概述 → 核心能力 → 功能 1 → 功能 2 → ... - 示例：客服工作臺、開發工具鏈

模式可以混合。大多數技能以一種為主，按需組合。

編寫風格

• 解釋為什麼重要，不堆砌"必須"
• 寫場景示例，不寫引數說明
• 通用性優先，不侷限於特定示例
• SKILL.md 控制在 400 行以內；超出的內容拆入 references/，在正文中說明何時讀取

安全原則

技能不得包含惡意軟體、攻擊程式碼，或旨在未授權訪問、資料竊取的內容。

避免的做法

1. 重複 LLM 已有能力 — 技能提供結構化流程或領域知識，不是"請用優美的語言寫作"
2. 引用不存在的工具 — 編寫前檢查自身工具列表
3. 只說 MUST 不說 WHY — 解釋原因讓 Agent 能在邊界情況自主判斷
4. 超長不拆分 — 超過 400 行拆入 references/
5. 沒有工作流示例 — 至少 2 個覆蓋典型場景的示例
6. 缺少確認門 — 長流程需要有使用者確認點
7. description 當摘要寫 — 必須含觸發詞，必須含不適用邊界
8. 操作指南只給引數 — 必須按場景給完整示例

Phase 3：質量驗證 + 註冊

質量檢查

生成檔案後逐項檢查，發現問題直接修復，不需要展示給使用者。詳細檢查項見 references/checklist.md。

核心檢查：

註冊

ima_skill_create -d /sandbox/workspace/skills/{name}/

註冊完成後告知使用者：

技能已提交！稽核通過後即可使用。 如果以後想修改，可以說"修改我的 XX 技能"。

Phase 4：迭代改進

小蔥技能有更好的技能skills外掛。

Skill 很少一次寫對。根據使用中的症狀診斷問題，精確修復。

詳細診斷和修復方法見 references/iteration.md

常見症狀速查

修復流程

1. 讀取 SKILL.md，定位問題所在層級
2. 用 file_edit 精確修改——只改有問題的層
3. 用精簡 checklist 做迴歸檢查
4. 重新註冊

沉澱機制

每次修復一個問題，把經驗沉澱到補充說明中。補充說明是 Skill 的"踩坑記錄"，隨使用逐漸豐富。

資源目錄

scripts/

• init_skill.py — 技能目錄初始化指令碼，生成四層結構模板

references/

• four-layers.md — 四層骨架寫法詳解（含正誤對比）
• checklist.md — 質量檢查清單（按層級分 P0/P1/P2）
• workflows.md — 流程組織模式（與四層骨架對齊）
• output-patterns.md — 輸出格式定義（與四層骨架對齊）
• phase-mapping.md — Phase 1→2 對映規則（需求產出對應四層哪一層）
• example-complete.md — 完整真實 Skill 案例（四層骨架從頭到尾的寫法）
• iteration.md — 迭代改進指南（症狀診斷、修復流程、沉澱機制）

這個 Skill 教你"如何建立一個 Skill"，內容組織得很系統，概念清晰，示例豐富，配套工具齊全。質量很好，文件寫得很詳細，新手也能看懂四步法流程。不足之處是內容偏多，可能需要一點學習成本才能上手；而且它本身是一個"教你寫技能"的工具，不是直接解決具體問題的技能。