Skill 編寫指南：目錄結構、參數與寫法詳解

應用場景

SKILL.md 規範係目前AI領域快速興起嘅「技能包」標準。佢可以幫你將日常嘅提示詞同工作流程，包裝成像App咁可以重用嘅模塊。

第一類：AI編程助手（開發者成日用）

喺開發工具入面，Skill最廣泛嘅應用係擴展AI嘅編碼能力，例如自動化代碼審查、生成項目文檔等。

• Cursor：一款智能代碼編輯器。佢支持從項目入面嘅 .cursor/skills/ 目錄讀取 SKILL.md 文件
• Claude Code：Anthropic 推出嘅命令行AI工具。佢會讀取項目或用戶目錄下面嘅 .claude/skills/ 

第二類：AI智能體平台同社區（應用生態）

呢類平台會將SKILL.md作為佢哋嘅「應用商店」或「技能市場」嘅標準格式，等用戶可以發現同安裝各種AI能力。

• ClawHub：一個專注於AI技能嘅市場，類似「Docker Hub」但係針對Skill。目前已經收錄超過5.2萬個技能，總下載量超過1200萬。
• 字節跳動、騰訊、飛書：旗下多閃、元寶、龍蝦等平台都有各自嘅「技能廣場」或「智能體技能市場」

一、Skill 係乜嘢？

Skill 係一套定義AI專屬能力嘅標準化文件夾工程，核心作用係幫AI設定明確嘅崗位職責、執行流程、輸入輸出規則同質量標準。

Skill = 一個文件夾  入面至少包含一個 SKILL.md 文件，用嚟定義 AI 嘅能力、流程同限制。

通俗啲講：Skill = AI嘅崗位說明書 + 標準化操作手冊 + 質量驗收規範。

二、最小 Skill 結構

my-first-skill/
└── SKILL.md

✅ 只要一個文件，Skill 就可以運行
✅ 先搞掂，再逐步增強

三、目錄結構解剖

my-skill/
├── SKILL.md    # 🧠 大腦：核心定義（必填），包含工作流與規則
├── agents/     # 🎭 人設：角色配置與展示信息（可選）
├── references/  # 📚 知識庫：長文檔、API 文檔、背景資料（可選）
├── scripts/    # 🛠️ 工具：Python/Shell 腳本，處理確定性邏輯（可選）
└── assets/     # 📦 素材：模板文件、圖片、字體、樣例數據（可選）

各模塊職責詳解

四、SKILL.md 編寫規範詳解

SKILL.md 係 Skill 嘅靈魂。佢由 Frontmatter（元數據） 和 Body（執行指令） 兩部分組成。

1. Frontmatter：身份同觸發機制

呢個係 YAML 格式嘅配置區，決定了 Skill 嘅「身份ID」同「觸發靈敏度」。

---
name: weekly-report-helper            # 唯一標識：小寫+連字符
description:># 觸發核心：決定 AI 何時調用此 Skill
  幫助運營人員自動生成周報。
  適用於分析 CSV 數據、總結核心指標變化。
  當用戶說“寫週報”、“分析數據”、“出覆盤”時觸發。
author: chinapmcc.com
version: 1.0.0
tags:[數據分析, 週報, 自動化]
---

關鍵參數解析：

● name：Skill 嘅身份證。一旦發佈，唔好用下劃線或者大小寫混用，儘量唔好改名，否則會導致歷史記錄失效。

● description：最重要嘅字段。

○ 公式：做什麼（能力） + 什麼時候用（場景） + 用戶會怎麼說（觸發詞）。

○ 技巧：描述越具體，AI 誤觸發率越低。

2. Body：執行指令（Prompt Engineering）

Body 係 AI 嘅執行腳本（「操作手冊」）。唔好寫空話，要寫可以執行嘅流程，要可以操作、可以檢查。

推薦嘅正文結構

# 核心目標
生成一份結構清晰的週報，包含核心指標變化、問題診斷和下步建議。

# 工作流程 (Workflow)
1.**數據讀取**：讀取用戶上傳的 CSV 或粘貼的數據。
2.**數據計算**：調用 `scripts/calc_change.py` 計算環比、同比數據。
3.**異常檢測**：識別波動超過 20% 的指標。
4.**內容生成**：參考 `references/style_guide.md` 的語氣，填充 `assets/template.md`。

# 輸入規則
- 必須包含日期、指標值。
- 至少需要 2 個時間週期的數據對比。

# 輸出格式
- 使用 Markdown 表格展示數據。
- 結論部分包含：3 條核心結論 + 2 條可執行建議。

# 質量檢查 (Self-Correction)
在輸出前，請自查：
- [ ] 是否解釋了所有異常波動？
- [ ] 建議是否具體可執行（非廢話）？
- [ ] 數據計算是否與腳本輸出一致？

核心目標

明確要達成啲乜嘢結果

• 解決乜嘢問題？
• 達到乜嘢效果？
• 成功嘅標準係乜嘢？

工作流程

按順序拆解可以執行嘅步驟

• 一步步做啲乜？
• 每一步嘅產出係乜嘢？
• 需要用啲乜嘢工具？

輸入規則

明確輸入要求同使用條件

• 需要啲乜嘢輸入資訊？
• 輸入格式係乜嘢？
• 有啲乜嘢限制條件？

輸出格式

定義輸出結構同呈現方式

• 輸出一啲乜嘢內容？
• 用乜嘢格式呈現？
• 包含乜嘢字段/模塊？

質量檢查

確保結果達標同可用

• 點樣自檢？
• 檢查啲乜嘢關鍵點？
• 唔符合點算？

1.少講背景，多講流程
2.用清單同步驟更清晰
3.具體可以執行，AI先至靠譜

「外掛裝備庫」

佢哋嘅核心作用係將非自然語言嘅任務（例如計數、格式化）從 AI 嘅大腦入面剝離出嚟，交給更可靠嘅工具處理。

🎭 1. agents/ —— 角色配置同展示資訊

📌 核心作用：
定義 AI 嘅「人設」同交互體驗。佢決定咗用戶喺界面上見到嘅名稱、簡介，同埋 AI 首次開口時嘅語氣。呢個目錄通常包含配置文件（例如 openai.yaml 或 anthropic.yaml）。

💡 典型內容：
顯示名稱（Display Name）、簡短描述（Short Description）、默認系統提示詞（Default Prompt）。

🛠️ 使用示例：
假設你喺做一個代碼審查助手，你可以創建一個 agents/openai.yaml 文件：

interface:
display_name: 資深架構師老王
short_description: 專注高併發系統的代碼審查與性能調優建議。
default_prompt:>
    你好！我是你的專屬架構師老王。我擁有 10 年分佈式系統經驗。
    請把代碼發給我，我會重點檢查內存泄漏、鎖競爭和 SQL 慢查詢問題。
    我的點評風格直接犀利，不講廢話。

📚 2. references/ —— 知識庫同背景資料

📌 核心作用：
存放長篇文檔、規範指南或 API 手冊。當任務涉及大量上下文嘅時候，AI 冇辦法靠記憶記住所有細節。將呢啲資料放喺呢度，AI 可以喺執行過程中按需要檢索（RAG），從而保持回答嘅專業性同準確性。

💡 典型內容：
公司代碼規範（Style Guide）、產品需求文檔（PRD）、API 接口說明、歷史覆盤報告。

🛠️ 使用示例：
你希望 AI 按照公司嘅嚴格標準寫 PR，可以喺該目錄下面放入 company_pr_rules.md。然後喺 SKILL.md 入面咁樣引用：

## 工作流程
1. 接收用戶的開發需求。
2. 讀取 `references/company_pr_rules.md`，確保生成的 PR 描述符合團隊規範。
3. 根據規範模板生成 Markdown 格式的 PR 文本。

🛠️ 3. scripts/ —— 確定性邏輯同自動化工具

📌 核心作用：
處理 AI 唔擅長嘅「硬邏輯」。大模型本質上係概率預測機，做數學計數、正則提取或文件轉換時極易出錯（幻覺）。將呢類任務寫成 Python 或 Shell 腳本，等 AI 充當「指揮官」，只係負責調用腳本同解讀結果。

💡 典型內容：
數據清洗腳本、格式轉換工具、環境依賴安裝器、單元測試運行器。

🛠️ 使用示例：
用戶要求分析一份 50MB 嘅 CSV 銷售日誌，揾出異常訂單。唔好俾 AI 去讀 CSV，而係寫一個 scripts/find_anomalies.py。在 SKILL.md 入面編排：

## 工作流程
1. 獲取用戶提供的 CSV 文件路徑。
2. 執行命令：`python scripts/find_anomalies.py --input <file_path>`。
3. 捕獲腳本的標準輸出（JSON 格式的異常訂單列表）。
4. 用通俗易懂的語言向用戶解釋這些異常訂單的原因。

📦 4. assets/ —— 靜態素材同標準化模板

📌 核心作用：
提供標準化嘅輸出骨架或多媒體資源。當你需要 AI 每次輸出嘅格式都完全一致（例如固定嘅郵件模板、特定嘅 JSON 結構），或者需要附帶圖片/字體嘅時候，呢個目錄係最佳選擇。

💡 典型內容：
Markdown 模板、JSON/YAML 結構樣例、佔位圖、品牌 Logo。

🛠️ 使用示例：
你需要 AI 幫你俾客戶發送標準化嘅週報郵件。喺 assets/ 下放置 weekly_email_template.md：

# {{client_name}} 項目週報 ({{date}})

## 🚀 本週進展
- {{progress_1}}
- {{progress_2}}

## ⚠️ 風險與阻礙
- {{risks}}

在 SKILL.md 入面指示 AI 填空：

## 輸出規則
1. 收集本週的項目進度和風險點。
2. 打開 `assets/weekly_email_template.md`。
3. 將收集到的信息填入對應的 `{{variable}}` 變量中。
4. 僅輸出最終的完整郵件正文，不要包含任何解釋性廢話。

呢四個目錄並唔係孤立嘅，佢哋通常喺 SKILL.md 嘅工作流入面被串聯起嚟。一個完整嘅自動化流程通常係咁樣嘅：

“以 agents/ 入面嘅專家身份，參考 references/ 入面嘅規範文檔，調用 scripts/ 完成數據處理，最後套用 assets/ 入面嘅模板輸出最終結果。」

五、最終建議

• ✅ 從最細結構開始
• ✅ 先寫清楚 description
• ✅ Body 用流程 + 清單
• ✅ 資源按目錄分開
• ✅ 俾一個真實示例測試

一個好嘅 Skill，唔係堆字數，而係等 AI 一睇就明、一跑就啱。

Previous Posts

應用場景

SKILL.md 規範是目前AI領域快速興起的"技能包"標準。它可以幫你把日常的提示詞和工作流程，封裝成像App一樣可複用的模塊。

第一類：AI編程助手（開發者常用）

在開發工具中，Skill最廣泛的應用是擴展AI的編碼能力，比如自動化代碼審查、生成項目文檔等。

• Cursor：一款智能代碼編輯器。它支持從項目中的 .cursor/skills/ 目錄讀取 SKILL.md 文件
• Claude Code：Anthropic 推出的命令行AI工具。它會讀取項目或用戶目錄下的 .claude/skills/ 

第二類：AI智能體平台與社區（應用生態）

這類平台將SKILL.md作為其"應用商店"或"技能市場"的標準格式，讓用戶能發現和安裝各種AI能力。

• ClawHub：一個專注於AI技能的市場，類似"Docker Hub"但針對Skill。目前已收錄超過5.2萬個技能，總下載量超1200萬。
• 字節跳動、騰訊、飛書：旗下多閃、元寶、龍蝦等平台也都有各自的"技能廣場"或"智能體技能市場"

一、Skill 是什麼？

Skill 是一套定義AI專屬能力的標準化文件夾工程，核心作用是給AI設定明確的崗位職責、執行流程、輸入輸出規則與質量標準。

Skill = 一個文件夾  裏面至少包含一個 SKILL.md 文件，用來定義 AI 的能力、流程和限制。

通俗類比：Skill = AI的崗位說明書 + 標準化操作手冊 + 質量驗收規範。

二、最小 Skill 結構

my-first-skill/
└── SKILL.md

✅ 只要一個文件，Skill 就能運行
✅ 先跑通，再逐步增強

三、目錄結構解剖

my-skill/
├── SKILL.md    # 🧠 大腦：核心定義（必填），包含工作流與規則
├── agents/     # 🎭 人設：角色配置與展示信息（可選）
├── references/  # 📚 知識庫：長文檔、API 文檔、背景資料（可選）
├── scripts/    # 🛠️ 工具：Python/Shell 腳本，處理確定性邏輯（可選）
└── assets/     # 📦 素材：模板文件、圖片、字體、樣例數據（可選）

各模塊職責詳解

四、SKILL.md 編寫規範詳解

SKILL.md 是 Skill 的靈魂。它由 Frontmatter（元數據） 和 Body（執行指令） 兩部分組成。

1. Frontmatter：身份與觸發機制

這是 YAML 格式的配置區，決定了 Skill 的“身份ID”和“觸發靈敏度”。

---
name: weekly-report-helper            # 唯一標識：小寫+連字符
description:># 觸發核心：決定 AI 何時調用此 Skill
  幫助運營人員自動生成周報。
  適用於分析 CSV 數據、總結核心指標變化。
  當用戶說“寫週報”、“分析數據”、“出覆盤”時觸發。
author: chinapmcc.com
version: 1.0.0
tags:[數據分析, 週報, 自動化]
---

關鍵參數解析：

● name：Skill 的身份證。一旦發佈，不要用下劃線或大小寫混用，儘量不要改名，否則會導致歷史記錄失效。

● description：最重要的字段。

○ 公式：做什麼（能力） + 什麼時候用（場景） + 用戶會怎麼說（觸發詞）。

○ 技巧：描述越具體，AI 誤觸發率越低。

2. Body：執行指令（Prompt Engineering）

Body 是 AI  的執行腳本（“操作手冊”）。不要寫空話，要寫可執行的流程，要可操作、可檢查。

推薦的正文結構

# 核心目標
生成一份結構清晰的週報，包含核心指標變化、問題診斷和下步建議。

# 工作流程 (Workflow)
1.**數據讀取**：讀取用戶上傳的 CSV 或粘貼的數據。
2.**數據計算**：調用 `scripts/calc_change.py` 計算環比、同比數據。
3.**異常檢測**：識別波動超過 20% 的指標。
4.**內容生成**：參考 `references/style_guide.md` 的語氣，填充 `assets/template.md`。

# 輸入規則
- 必須包含日期、指標值。
- 至少需要 2 個時間週期的數據對比。

# 輸出格式
- 使用 Markdown 表格展示數據。
- 結論部分包含：3 條核心結論 + 2 條可執行建議。

# 質量檢查 (Self-Correction)
在輸出前，請自查：
- [ ] 是否解釋了所有異常波動？
- [ ] 建議是否具體可執行（非廢話）？
- [ ] 數據計算是否與腳本輸出一致？

核心目標

明確要達成什麼結果

• 解決什麼問題？
• 達到什麼效果？
• 成功的標準是什麼？

工作流程

按順序拆解可執行的步驟

• 一步步做什麼？
• 每一步的產出是什麼？
• 需要用到哪些工具？

輸入規則

明確輸入要求與使用條件

• 需要哪些輸入信息？
• 輸入格式是什麼？
• 有哪些限制條件？

輸出格式

定義輸出結構與呈現方式

• 輸出什麼內容？
• 用什麼格式呈現？
• 包含哪些字段/模塊？

質量檢查

確保結果達標與可用

• 如何自檢？
• 檢查哪些關鍵點？
• 不符合怎麼辦？

1.少講背景，多講流程
2.用清單和步驟更清晰
3.具體可執行，AI才靠譜

“外掛裝備庫”

它們的核心作用是將非自然語言的任務（如計算、格式化）從 AI 的大腦中剝離出來，交由更可靠的工具處理。

🎭 1. agents/ —— 角色配置與展示信息

📌 核心作用：
定義 AI 的“人設”和交互體驗。它決定了用戶在界面上看到的名稱、簡介，以及 AI 首次開口時的語氣。這個目錄通常包含配置文件（如 openai.yaml 或 anthropic.yaml）。

💡 典型內容：
顯示名稱（Display Name）、簡短描述（Short Description）、默認系統提示詞（Default Prompt）。

🛠️ 使用示例：
假設你在做一個代碼審查助手，你可以創建一個 agents/openai.yaml 文件：

interface:
display_name: 資深架構師老王
short_description: 專注高併發系統的代碼審查與性能調優建議。
default_prompt:>
    你好！我是你的專屬架構師老王。我擁有 10 年分佈式系統經驗。
    請把代碼發給我，我會重點檢查內存泄漏、鎖競爭和 SQL 慢查詢問題。
    我的點評風格直接犀利，不講廢話。

📚 2. references/ —— 知識庫與背景資料

📌 核心作用：
存放長篇文檔、規範指南或 API 手冊。當任務涉及大量上下文時，AI 無法靠記憶記住所有細節。將這些資料放在這裏，AI 可以在執行過程中按需檢索（RAG），從而保持回答的專業性和準確性。

💡 典型內容：
公司代碼規範（Style Guide）、產品需求文檔（PRD）、API 接口說明、歷史覆盤報告。

🛠️ 使用示例：
你希望 AI 按照公司的嚴格標準寫 PR，可以在該目錄下放入 company_pr_rules.md。然後在 SKILL.md 中這樣引用：

## 工作流程
1. 接收用戶的開發需求。
2. 讀取 `references/company_pr_rules.md`，確保生成的 PR 描述符合團隊規範。
3. 根據規範模板生成 Markdown 格式的 PR 文本。

🛠️ 3. scripts/ —— 確定性邏輯與自動化工具

📌 核心作用：
處理 AI 不擅長的“硬邏輯”。大模型本質上是概率預測機，做數學計算、正則提取或文件轉換時極易出錯（幻覺）。將這類任務寫成 Python 或 Shell 腳本，讓 AI 充當“指揮官”，只負責調用腳本並解讀結果。

💡 典型內容：
數據清洗腳本、格式轉換工具、環境依賴安裝器、單元測試運行器。

🛠️ 使用示例：
用戶要求分析一份 50MB 的 CSV 銷售日誌，找出異常訂單。不要讓 AI 去讀 CSV，而是寫一個 scripts/find_anomalies.py。在 SKILL.md 中編排：

## 工作流程
1. 獲取用戶提供的 CSV 文件路徑。
2. 執行命令：`python scripts/find_anomalies.py --input <file_path>`。
3. 捕獲腳本的標準輸出（JSON 格式的異常訂單列表）。
4. 用通俗易懂的語言向用戶解釋這些異常訂單的原因。

📦 4. assets/ —— 靜態素材與標準化模板

📌 核心作用：
提供標準化的輸出骨架或多媒體資源。當你需要 AI 每次輸出的格式都完全一致（例如固定的郵件模板、特定的 JSON 結構），或者需要附帶圖片/字體時，這個目錄是最佳選擇。

💡 典型內容：
Markdown 模板、JSON/YAML 結構樣例、佔位圖、品牌 Logo。

🛠️ 使用示例：
你需要 AI 幫你給客戶發送標準化的週報郵件。在 assets/ 下放置 weekly_email_template.md：

# {{client_name}} 項目週報 ({{date}})

## 🚀 本週進展
- {{progress_1}}
- {{progress_2}}

## ⚠️ 風險與阻礙
- {{risks}}

在 SKILL.md 中指示 AI 填空：

## 輸出規則
1. 收集本週的項目進度和風險點。
2. 打開 `assets/weekly_email_template.md`。
3. 將收集到的信息填入對應的 `{{variable}}` 變量中。
4. 僅輸出最終的完整郵件正文，不要包含任何解釋性廢話。

這四個目錄並不是孤立的，它們通常在 SKILL.md 的工作流中被串聯起來。一個完整的自動化流程通常是這樣的：

“以 agents/ 中的專家身份，參考 references/ 中的規範文檔，調用 scripts/ 完成數據處理，最後套用 assets/ 中的模板輸出最終結果。”

五、最終建議

• ✅ 從最小結構開始
• ✅ 先寫清楚 description
• ✅ Body 用流程 + 清單
• ✅ 資源按目錄分開
• ✅ 給一個真實示例測試

一個好的 Skill，不是堆字數，而是讓 AI 一看就懂、一跑就對。

Previous Posts