本文以一個真實案例——「SEO 健檢」技能的誕生全過程——總結建立 SKILL 需要做的工作、用到的指令，以及踩過的坑。適合想把自己的重複性工作流程固化為可重複使用技能的人。
一、什麼是 SKILL，為什麼要建立
SKILL 是把一套多步驟工作流程固化下來的可重複使用能力包。一次做好，之後一句話就能觸發整套流程，不必每次重新交代。
一個 SKILL 本質上是一個資料夾：
skill-name/
├── SKILL.md ← 核心：流程说明 + 触发词 + 输入 + 经验
├── scripts/ ← 可选：可复用的代码脚本
│ └── *.py
└── evals/ ← 可选：测试用例
└── evals.json
適合做成 SKILL 的訊號：這件事你會重複做、步驟 ≥2、有明確產出物、換個對象（URL/客戶/專案）還能用。
二、建立 SKILL 的整體流程（5 步）
建立技能本身也有一個「元技能」來引導。核心是這 5 步：
| 步驟 | 做什麼 | 用到的指令/工具 |
|---|---|---|
| 1. 先把工作流程真正跑通一遍 | 用真實任務完整做一次，產出真實成果 | 正常對話即可 |
| 2. 確認技能骨架 | 設定技能名稱、顯示名稱、觸發詞、輸入項、圖示 | 與 AI 確認 |
| 3. 擷取工作階段資料 | 自動擷取用過的工具、產生骨架 | extract_session_data |
| 4. 撰寫 SKILL.md | 補全流程、經驗、腳本 | AI 產生，人工審核 |
| 5. 儲存 + 測試 | 存入技能庫、產生測試案例 | save_skill + generate_skill_evals |
三、逐步拆解：每一步具體做什麼
步驟 1：先跑通工作流程（最重要）
別急著建技能。先拿一個真實需求完整做一遍，例如：「幫我檢查這個網頁的 SEO」。在這個過程中：
- 明確輸入是什麼（一個 URL？一批 URL？）
- 明確產出是什麼（一份報告？什麼格式？）
- 記錄每一步用了什麼能力（開啟網頁、執行程式碼、產生 Excel……）
實戰教訓：我們的 SEO 技能，是先真刀真槍審查了某企業官網的多個頁面、反覆調整報告格式後，才提煉成技能的。過程中使用者不斷提要求（加入 Bing 標準、核實官方來源、改成執行矩陣、拆成兩階段……），這些都成了技能裡最有價值的部分。
步驟 2：確認技能骨架
跟 AI 說清楚（或讓它建議）：
| 專案 | 說明 | 範例 |
|---|---|---|
| 技能名稱 | 小寫連字號，內部識別 | seo-audit-skill |
| 顯示名稱 | 給人看的名稱 | 「SEO 健檢」 |
| 觸發詞 | 哪些話該啟動它 | 「SEO健檢 / 網站優化 / 檢查頁面SEO」 |
| 輸入項 | 每次會變的東西 | page_url、audit_scope |
| 圖示 | 一個 emoji | 🔍 |
步驟 3：擷取工作階段資料
這一步由工具自動完成：掃描剛才跑通的工作階段，抽出用過的工具清單，產生一個帶 YAML frontmatter 的 SKILL.md 骨架。你只要提供步驟 2 定好的：技能名、觸發詞、輸入項、顯示名、圖示。
指令：extract_session_data
步驟 4：寫 SKILL.md（核心創作）
在骨架基礎上補全以下部分：
① frontmatter（檔案標頭）
---
name: seo-audit-skill
display_name: 「SEO 体检」
description: "一句话说清楚它做什么、什么时候该触发"
icon: "🔍"
trigger: SEO体检 audit 网站优化 网站SEO
inputs:
- name: page_url
description: "要体检的页面网址"
required: true
scripts: [seo_audit.py, seo_matrix.py]
---
② Overview
2–3 句說清做什麼、何時用。
③ Workflow（分步驟）
每步標註模式（deterministic 固定動作 / agentic 需判斷）、輸入、輸出、驗證方式、失敗怎麼辦。多講「為什麼」，少寫死板的「必須/禁止」——執行技能的 AI 更吃「講道理」。
④ Output
最終產出長什麼樣，定義清楚格式。
⑤ Lessons Learned（經驗）
這是技能品質的分水嶺，分四塊：
- Do：哪些做法有效
- Don't：哪些坑別踩
- Common Failures：常見錯誤 + 應對
- When to Ask the User：什麼時候該停下來問人
實戰教訓：我們這個技能的 Lessons 裡寫滿了真實踩過的坑——中文別用\uXXXX轉義、寫 CSV 用utf-8-sig防 Excel 亂碼、圖片 alt 缺失率異常高多半是延遲載入誤報（要標「待核」而非直接判缺）、部分網域會封鎖批次抓取，需用瀏覽器驗證……這些「血淚」讓技能下次跑得更穩。
⑥ 腳本（可選但強烈推薦）
如果流程裡有重複寫的程式碼，抽成腳本放 scripts/，在 SKILL.md 裡引用。我們把「頁面訊號採集 JS」和「多頁矩陣生成」做成兩個腳本，保證輸出格式每次一致。
步驟 5：儲存 + 測試
- 儲存指令：
save_skill（技能名 + 完整 SKILL.md + 腳本） - 生成測試：
generate_skill_evals（自動造幾個測試案例） - 然後真跑一次驗證——我們分別用單頁、多頁兩種場景實測，確認能識別真實問題（比如揪出若干 404 壞連結、發現社群分享標題與頁面標題不一致）。
四、建立後如何迭代與分發
迭代改進
指令：load_skill_for_improvement。技能不是一次成型的。用了幾次後按需改進：
- 改流程、加輸出格式、調觸發詞
- 儲存時用同一個技能名即可原地覆蓋（會自動備份舊版）
實戰：我們這個技能迭代了很多輪——加 Bing 標準、改執行矩陣格式、拆成兩階段、加 Excel+Markdown 雙輸出、修列名對齊範例、最後改名。每輪都是load_skill_for_improvement→ 改 →save_skill覆蓋。
重新命名
改 frontmatter 裡的 name 和 display_name，用新名 save_skill，再刪掉舊技能資料夾。
打包分發
把整個技能資料夾壓成 zip，即可備份、遷移到別的電腦、或分享給同事（放進對方的 skills 目錄）。
跨工具移植
如果要在別的 AI 工具（ChatGPT/Claude/Gemini）用，需要「去平台化」：把專有工具名改寫成通用能力描述（「開啟網頁」「執行程式碼」），並把腳本內嵌成自包含的 Markdown，即可整段貼上為系統提示/自訂指令。
五、常用指令速查
| 指令 | 作用 | 用在 |
|---|---|---|
extract_session_data | 從會話抽取骨架 | 建立·步驟 3 |
save_skill | 儲存/覆寫技能 | 建立·步驟 5 / 迭代 |
generate_skill_evals | 產生測試案例 | 建立·步驟 5 |
load_skill_for_improvement | 載入技能以改進 | 迭代 |
六、避坑清單（來自真實踩坑）
- 先跑通再固化——別憑空寫技能。
- 輸入只放會變的——固定值寫死在流程裡。
- Lessons Learned 要寫滿真實經驗——這是技能能不能「越用越穩」的關鍵。
- 重複程式碼抽成腳本——保證輸出格式一致、省 token。
- 儲存後必測——真跑一次單頁 + 多頁，驗證它能識別真實問題。
- 編碼坑（若涉及中文/程式碼產生）：寫檔案用
encoding="utf-8"，CSV 用utf-8-sig，別用\uXXXX轉義，PDF 中文用內建 CID 字型。 - 迭代用同名覆寫——
name不變，自動備份舊版。
結語
建立 SKILL 的本質是：把一次成功的工作流，連同其中的判斷與教訓，一起封裝成「下次一句話就能重來」的能力。 做得好的技能，不只是記錄了步驟，更記錄了「怎麼把這件事做對」的經驗。
先把事情做漂亮，再讓它可重複使用——這就是建立 SKILL 的全部心法。
