AI Skills
skill-writer

skill-writer

熱門

引導使用者為 Claude Code 建立 Agent Skills。當使用者想要建立、撰寫、創作或設計新的 Skill，或是需要處理 SKILL.md 檔案、frontmatter 設定或 Skill 結構時使用。

10萬星標
2.9萬分支
更新於 2026/7/31
獲取技能源代碼

相關技能

fsharp-testing24萬dogfood22萬next-cache-components-optimizer14萬
SKILL.md
唯讀
名稱
skill-writer
描述

引導使用者為 Claude Code 建立 Agent Skills。當使用者想要建立、撰寫、創作或設計新的 Skill，或是需要處理 SKILL.md 檔案、frontmatter 設定或 Skill 結構時使用。

Skill Writer

本 Skill 旨在協助你為 Claude Code 建立結構良好、符合最佳做法與驗證規範的 Agent Skills。

何時使用此 Skill

在以下情境時使用此 Skill：

  • 建立新的 Agent Skill
  • 撰寫或更新 SKILL.md 檔案
  • 設計 Skill 結構與 frontmatter
  • 排查 Skill 找不到或無法載入等問題
  • 將現有的 Prompt 或工作流程轉換為 Skills

指引說明

步驟 1：確定 Skill 的作用範圍

首先，釐清這個 Skill 應該具備哪些功能：

  1. 提出澄清問題：

    • 此 Skill 具體應該提供什麼功能？
    • Claude 應該在什麼時機使用此 Skill？
    • 它需要哪些工具或資源？
    • 這是供個人使用，還是團隊共享？

  2. 保持專一：一個 Skill 專注於一項功能

    • 良好範例：「PDF 表單填寫」、「Excel 資料分析」
    • 範圍過大：「文件處理」、「資料工具」

步驟 2：選擇 Skill 的存放位置

決定要在哪裡建立 Skill：

個人 Skills (~/.claude/skills/)：

  • 個人專用的工作流程與偏好設定
  • 實驗性質的 Skills
  • 個人生產力工具

專案 Skills (.claude/skills/)：

  • 團隊工作流程與規範
  • 專案特定的專業知識
  • 共享工具（需提交至 git）

步驟 3：建立 Skill 結構

建立目錄與檔案：

# 個人
mkdir -p ~/.claude/skills/skill-name

# 專案
mkdir -p .claude/skills/skill-name

如果是包含多個檔案的 Skill：

skill-name/
├── SKILL.md (必填)
├── reference.md (選填)
├── examples.md (選填)
├── scripts/
│   └── helper.py (選填)
└── templates/
    └── template.txt (選填)

步驟 4：撰寫 SKILL.md 的 frontmatter

建立包含必要欄位的 YAML frontmatter：

---
name: skill-name
description: 簡述此 Skill 的功能與使用時機
---

欄位要求：

  • name：

    • 僅能包含小寫英文字母、數字與連字號（-）
    • 長度上限為 64 個字元
    • 必須與目錄名稱一致
    • 良好範例：pdf-processor、git-commit-helper
    • 不良範例：PDF_Processor、Git Commits!

  • description：

    • 長度上限為 1024 個字元
    • 必須同時包含「功能說明」與「使用時機」
    • 加入使用者會說的具體觸發詞
    • 提及相關的檔案類型、操作與上下文情境

可選的 frontmatter 欄位：

  • allowed-tools：限制可用的工具存取權限（以逗號分隔）
    allowed-tools: Read, Grep, Glob
    適用情境：
    • 唯讀性質的 Skills
    • 涉及安全敏感的工作流程
    • 限制操作範圍的情境

步驟 5：撰寫高效的 description

description 是 Claude 是否能順利觸發並找到 Skill 的關鍵。

撰寫公式：[功能說明] + [使用時機] + [核心觸發詞]

範例：

✅ 良好範例：

description: 從 PDF 檔案擷取內文與表格、填寫表單及合併文件。當處理 PDF 檔案，或是使用者提及 PDF、表單或文件擷取時使用。

✅ 良好範例：

description: 分析 Excel 工作表、建立樞紐分析表並產生圖表。當處理 Excel 檔案、工作表或分析 .xlsx 格式的表格資料時使用。

❌ 過於模糊：

description: 協助處理文件
description: 用於資料分析

技巧：

  • 包含具體的檔案副檔名（.pdf, .xlsx, .json）
  • 提及常見的使用者用語（「分析」、「擷取」、「產生」）
  • 列出具體的操作（避免使用抽象泛用的動詞）
  • 加入情境提示（「當...時使用」、「適用於...」）

步驟 6：規劃 Skill 的內容結構

使用清晰的 Markdown 區塊：

# Skill 名稱

簡述此 Skill 的主要功能。

## 快速上手

提供簡單範例，便於立即開始使用。

## 指引說明

給 Claude 的步驟化引導：
1. 第一步：包含明確的動作
2. 第二步：預期的執行結果
3. 處理邊界情況（Edge cases）

## 實用範例

提供包含程式碼或命令的具體使用範例。

## 最佳做法

- 需遵循的核心規範
- 應避免的常見陷阱
- 適用與不適用的情境

## 前置需求

列出所需的依賴套件或前置條件：
```bash
pip install package-name

進階用法

關於更複雜的情境，請參閱 reference.md。


#### 步驟 7：新增附屬檔案（選填）

建立其他檔案以實現漸進式揭露（Progressive disclosure）：

**reference.md**：詳細的 API 文件、進階選項
**examples.md**：延伸範例與應用情境
**scripts/**：輔助指令稿與公用程式
**templates/**：檔案範本或樣板程式碼

在 SKILL.md 中引用這些檔案：
```markdown
關於進階用法，請參閱 [reference.md](reference.md)。

執行輔助指令稿：
\`\`\`bash
python scripts/helper.py input.txt
\`\`\`

步驟 8：驗證 Skill

檢查以下各項要求：

✅ 檔案結構：

  • [ ] SKILL.md 存在於正確位置
  • [ ] 目錄名稱與 frontmatter 中的 name 一致

✅ YAML frontmatter：

  • [ ] 第一行以 --- 開頭
  • [ ] 正文前以 --- 結尾
  • [ ] 格式為有效的 YAML（無 Tab 鍵，縮排正確）
  • [ ] name 符合命名規則
  • [ ] description 具體明確且字數少於 1024 字

✅ 內容品質：

  • [ ] 提供給 Claude 的指引清晰明確
  • [ ] 提供具體實用的範例
  • [ ] 已考量並處理邊界情況
  • [ ] 已列出依賴套件（若有）

✅ 測試驗證：

  • [ ] description 涵蓋使用者的常見提問
  • [ ] Skill 能在相關查詢中成功觸發
  • [ ] 指引內容清晰且可執行

步驟 9：測試 Skill

  1. 重新啟動 Claude Code（若正處於執行狀態），以載入新的 Skill

  2. 提出符合描述的相關問題：

    你能幫我從這個 PDF 檔案中擷取文字嗎？

  3. 確認觸發狀態：Claude 應會自動調用該 Skill

  4. 檢查執行行為：確認 Claude 是否準確遵循指引說明

步驟 10：問題排查與除錯

若 Claude 沒有使用該 Skill：

  1. 提高 description 的精確度：

    • 新增觸發關鍵字
    • 包含相關的檔案類型
    • 提及使用者的常用用語

  2. 檢查檔案存放路徑：

    ls ~/.claude/skills/skill-name/SKILL.md
ls .claude/skills/skill-name/SKILL.md

  3. 驗證 YAML 格式：

    cat SKILL.md | head -n 10

  4. 啟用除錯模式：

    claude --debug

常見模式

唯讀型 Skill

---
name: code-reader
description: 僅讀取與分析程式碼，不進行任何修改。用於程式碼審查、理解程式碼庫或撰寫文件。
allowed-tools: Read, Grep, Glob
---

基於指令稿的 Skill

---
name: data-processor
description: 使用 Python 指令稿處理 CSV 和 JSON 資料檔。在分析資料檔或轉換資料集時使用。
---

# Data Processor

## 指引說明

1. 使用資料處理指令稿：
\`\`\`bash
python scripts/process.py input.csv --output results.json
\`\`\`

2. 驗證輸出結果：
\`\`\`bash
python scripts/validate.py results.json
\`\`\`

採用漸進式揭露的多檔案 Skill

---
name: api-designer
description: 遵循最佳做法設計 REST API。在建立 API 端點、設計路由或規劃 API 架構時使用。
---

# API Designer

快速上手：請參閱 [examples.md](examples.md)

詳細參考資料：請參閱 [reference.md](reference.md)

## 指引說明

1. 收集需求
2. 設計端點（請參閱 examples.md）
3. 撰寫 OpenAPI 規格文件
4. 對照最佳做法進行審查（請參閱 reference.md）

給 Skill 作者的最佳做法

  1. 單一 Skill，單一目標：避免建立過於龐大的 Mega-Skill
  2. 描繪具體的 description：包含使用者會說出口的觸發詞
  3. 清晰明確的指引：指引是寫給 Claude 看的，而非人類
  4. 提供具體範例：展示真實程式碼，避免使用偽程式碼
  5. 標註依賴套件：在描述中列出所需的套件或工具
  6. 與團隊成員共同測試：驗證觸發準確度與說明清晰度
  7. 維護 Skill 的版本：在內容中記錄異動歷程
  8. 運用漸進式揭露：將進階細節移至獨立的檔案中

驗證檢查清單

在完成 Skill 之前，請確認：

  • [ ] 名稱僅包含小寫英文字母、連字號，長度在 64 字元以內
  • [ ] description 內容具體且長度少於 1024 字元
  • [ ] description 同時涵蓋「功能」與「時機」
  • [ ] YAML frontmatter 格式正確無誤
  • [ ] 指引說明具備循序漸進的步驟
  • [ ] 範例真實且具體可行
  • [ ] 已完整記錄所需的依賴套件
  • [ ] 檔案路徑均使用正斜線 (/)
  • [ ] Skill 能在相關查詢中成功觸發
  • [ ] Claude 能準確遵循指引說明

疑難排解

Skill 無法觸發：

  • 在 description 中加入更具體的觸發關鍵字
  • 描述中包含相關的檔案類型與操作
  • 加入帶有使用者常用語句的「當...時使用」子句

多個 Skill 產生衝突：

  • 提高不同 Skill 描述之間的辨識度與差異
  • 使用不同的觸發關鍵字
  • 縮小各個 Skill 的作用範圍

Skill 發生錯誤：

  • 檢查 YAML 語法（不可使用 Tab 鍵、注意縮排）
  • 確認檔案路徑（使用正斜線 /）
  • 確保指令稿具備可執行權限
  • 完整列出所有前置依賴套件

範例參考

請參閱完整範例文件：

  • 單一檔案的簡單 Skill (commit-helper)
  • 具備工具權限控管的 Skill (code-reviewer)
  • 多檔案 Skill (pdf-processing)

輸出格式規範

在建立 Skill 時，我將會：

  1. 提出澄清問題以釐清作用範圍與需求
  2. 建議合適的 Skill 名稱與存放位置
  3. 建立帶有正確 frontmatter 的 SKILL.md 檔案
  4. 撰寫清晰的指引說明與具體範例
  5. 視需要新增附屬支援檔案
  6. 提供測試引導說明
  7. 對照所有規範要求進行驗證

最終產出將會是一個符合所有最佳做法與驗證規則、可完整運作的 Skill。