Skills 實用技巧：最佳實踐、疑難排解與 30 個靈感清單

name: pdf-editor
name: api-tester
name: blog-writer
name: code-reviewer

name: PDF Editor        # 不要用空格和大寫
name: apiTester         # 不要用駝峰式命名
name: Blog_Writer       # 不要用底線
name: skill-1           # 不要用無意義的名稱

# Scripts
✅ generate_report.py
✅ run_tests.sh
✅ check_format.py

❌ GenerateReport.py
❌ runTests.sh
❌ script1.py

# References
✅ api-documentation.md
✅ style-guide.md
✅ database-schema.md

❌ ApiDocumentation.md
❌ styleGuide.md
❌ docs.md

# Assets
✅ company-logo.png
✅ report-template.html
✅ font-regular.ttf

❌ Company Logo.png
❌ template.html
❌ file.ttf

description: Helps with PDFs

description: 綜合 PDF 操作工具，支援提取文字和表格、建立新 PDF、合併/分割文件、旋轉頁面、處理表單。當需要程式化操作 PDF 檔案、提取 PDF 內容、或修改 PDF 文件時使用此 Skill。

description: 自動化 API 整合測試工具。用於執行微服務間的整合測試、驗證 API 回應、產生測試報告。適用於 CI/CD 流程、部署前驗證、或手動測試需求。當需要測試多個 API 端點、驗證服務間通訊時使用。

description: Use this skill when you want to create blog posts

description: 此 Skill 應用於需要撰寫技術部落格文章時

description: 程式碼審查助手。自動檢查程式碼風格、潛在錯誤、效能問題、安全漏洞。支援 JavaScript、Python、Go、Rust。當需要 code review、檢查程式碼品質、辨識 bug、或執行靜態分析時使用此 Skill。

You should check the API documentation before making requests.
If you want to test an endpoint, you can use the test script.

To make API requests, consult `references/api-docs.md` for endpoint specifications.
To test endpoints, execute `scripts/test_endpoint.py` with required parameters.

You might want to consider using the script if you feel like it.
This is probably the best way to do it.

Use `scripts/process_data.py` for batch data processing.
This approach ensures data consistency and reduces processing time by 70%.

# Skill 名稱

## 目的
[2-3 句話說明用途]

## 使用時機
[清楚的使用場景列表]

## 快速開始
[最簡單的使用範例]

## 操作指引
[詳細的步驟]

## 檔案說明
[說明各個 scripts/references/assets 的用途]

## 範例
[實際使用範例]

## 疑難排解
[常見問題和解決方案]

references/pdf-rotation-code.md

# PDF 旋轉程式碼

\`\`\`python
from PyPDF2 import PdfReader, PdfWriter

def rotate_pdf(input_path, output_path, degrees):
    reader = PdfReader(input_path)
    writer = PdfWriter()
    # ... 200 行程式碼
\`\`\`

scripts/rotate_pdf.py

#!/usr/bin/env python3
# 可直接執行，不佔用上下文

# SKILL.md

## API Endpoints

### User Service
- GET /api/users
- POST /api/users
... (列舉 100 個端點)

# SKILL.md

## API Endpoints

參考 `references/api-endpoints.md` 獲取完整 API 清單。

使用 grep 搜尋特定服務：
\`\`\`bash
grep "user-service" references/api-endpoints.md
\`\`\`

## 使用資料庫 Schema

`references/database-schema.md` 包含所有資料表定義（約 15,000 字）。

**不要完整讀取**，使用這些搜尋模式：

\`\`\`bash
# 搜尋特定資料表
grep -A 20 "## users table" references/database-schema.md

# 搜尋特定欄位
grep -B 5 "email_address" references/database-schema.md

# 搜尋關聯
grep "foreign key" references/database-schema.md
\`\`\`

**常用資料表：**
- users - 使用者基本資訊
- orders - 訂單記錄
- products - 產品目錄
- payments - 支付資訊

description: A skill for PDFs

description: PDF 操作工具，支援提取文字、合併、分割、旋轉頁面。當需要處理 PDF 檔案、提取 PDF 內容、或修改 PDF 文件時使用此 Skill。

# 檢查已安裝的 Skills
/plugin list

# 確認 Skill 在列表中
# 如果沒有，重新安裝
/plugin install /path/to/skill.zip

# SKILL.md (10,000 字)

## API Endpoints
[列舉 100 個端點的完整文件...]

## Database Schema
[列舉 50 個資料表的完整定義...]

# SKILL.md (2,000 字)

## API Endpoints
參考 `references/api-endpoints.md`

使用 grep 搜尋特定端點。

## Database Schema
參考 `references/database-schema.md`

使用搜尋模式找到需要的資料表。

## 處理圖片

使用以下程式碼：
\`\`\`python
# 500 行圖片處理程式碼...
\`\`\`

## 處理圖片

執行：
\`\`\`bash
python scripts/process_image.py --input image.jpg --output result.jpg
\`\`\`

# 檢查重複
diff SKILL.md references/guide.md

## 安裝相依套件

\`\`\`bash
pip install -r requirements.txt
\`\`\`

#!/usr/bin/env python3
"""
需求：
- Python 3.8+
- pip install -r requirements.txt
"""

import sys

# 檢查相依套件
try:
    import requests
    import pandas as pd
except ImportError as e:
    print(f"錯誤：缺少必要套件", file=sys.stderr)
    print(f"請執行：pip install -r requirements.txt", file=sys.stderr)
    sys.exit(1)

import os
from pathlib import Path

# 取得腳本所在目錄
SCRIPT_DIR = Path(__file__).parent
SKILL_DIR = SCRIPT_DIR.parent

# 使用相對路徑
data_file = SKILL_DIR / "assets" / "data.json"

# 確保腳本可執行
chmod +x scripts/*.py

# 確保輸出目錄可寫入
mkdir -p output
chmod 755 output

# scripts/my_script.py

import argparse

parser = argparse.ArgumentParser()
parser.add_argument('--verbose', '-v', action='store_true',
                    help='詳細輸出')
args = parser.parse_args()

def log(message, level='INFO'):
    if args.verbose or level == 'ERROR':
        print(f"[{level}] {message}", file=sys.stderr)

log("正在載入設定檔...", 'DEBUG')
log("處理完成", 'INFO')

python scripts/my_script.py --verbose

## 疑難排解

### Script 執行失敗

1. **檢查相依套件：**
   \`\`\`bash
   pip list | grep -E "(requests|pandas)"
   \`\`\`

2. **啟用詳細模式：**
   \`\`\`bash
   python scripts/run_tests.py --verbose
   \`\`\`

3. **查看日誌：**
   \`\`\`bash
   tail -f logs/skill.log
   \`\`\`

### 常見錯誤訊息

#### "ModuleNotFoundError"
**原因：** 缺少 Python 套件
**解決：** `pip install -r requirements.txt`

#### "Permission denied"
**原因：** 腳本沒有執行權限
**解決：** `chmod +x scripts/*.py`

#### "File not found"
**原因：** 路徑不正確
**解決：** 確認檔案存在，使用絕對路徑

# tests/test_script.py

import unittest
from scripts.generate_report import generate_report

class TestReportGeneration(unittest.TestCase):
    def test_basic_report(self):
        result = generate_report(data={'test': 123})
        self.assertIn('test', result)

    def test_empty_data(self):
        with self.assertRaises(ValueError):
            generate_report(data={})

if __name__ == '__main__':
    unittest.main()

---
name: my-skill
description: ...
version: 2.1.0
author: Your Name
changelog: |
  v2.1.0 (2025-01-20):
    - 新增：批次處理功能
    - 修正：UTF-8 編碼問題
    - 優化：效能提升 40%

  v2.0.0 (2025-01-01):
    - 重大更新：重寫核心邏輯
    - 新增：支援新的檔案格式
    - 移除：deprecated API

  v1.0.0 (2024-12-01):
    - 初版發布
---

# 建立版本標籤
git tag -a v2.1.0 -m "Release version 2.1.0"
git push origin v2.1.0

# 檢出特定版本
git checkout v2.0.0

# 列出所有版本
git tag -l

功能：自動程式碼審查
- 檢查程式碼風格
- 辨識常見錯誤模式
- 建議效能優化
- 檢查安全漏洞

功能：產生符合規範的 commit message
- 分析程式碼變更
- 產生語意化 commit message
- 支援 Conventional Commits 格式

功能：自動產生單元測試
- 分析函數簽名
- 產生測試案例
- 包含 edge cases
- 支援多種測試框架

功能：從程式碼產生 API 文件
- 解析程式碼註解
- 產生 OpenAPI/Swagger 規格
- 包含範例請求/回應

功能：檢查並更新相依套件
- 檢查過期套件
- 辨識安全漏洞
- 產生更新建議
- 生成更新 PR

功能：多平台社群貼文產生器
- 針對不同平台最佳化
- 自動產生 hashtags
- 建議發文時間
- 包含配圖建議

功能：電子報內容產生器
- 套用公司模板
- 分段和格式化
- 包含 CTA
- 產生純文字版本

功能：SEO 優化建議
- 關鍵字分析
- 標題優化建議
- Meta description 產生
- 內部連結建議

功能：影片腳本產生器
- 結構化腳本格式
- 時間碼標記
- 畫面描述
- 旁白文字

功能：Podcast 節目筆記產生器
- 時間戳章節標記
- 重點摘要
- 資源連結整理
- 逐字稿格式化

功能：配色方案產生器
- 根據品牌色產生色票
- 檢查對比度
- 提供 HEX/RGB 代碼
- 產生預覽圖

功能：Figma 設計轉程式碼
- 分析設計稿
- 產生 HTML/CSS
- React 元件產生
- 響應式設計支援

功能：無障礙設計檢查
- 色彩對比檢查
- 文字大小檢查
- 鍵盤導航測試
- ARIA 標籤建議

功能：圖示產生器
- 多尺寸輸出
- 不同格式（SVG, PNG）
- 符合設計系統
- favicon 產生

功能：設計系統文件產生器
- 元件文件
- 使用範例
- 程式碼片段
- 互動示範

功能：CSV 資料分析工具
- 自動偵測欄位類型
- 基本統計分析
- 資料視覺化
- 異常值偵測

功能：JSON 格式驗證與轉換
- Schema 驗證
- 格式化和美化
- JSON ↔ YAML 轉換
- 錯誤訊息說明

功能：日誌檔案分析工具
- 錯誤模式辨識
- 效能瓶頸分析
- 時間序列圖表
- 異常偵測

功能：資料清理與標準化
- 移除重複項
- 格式標準化
- 缺失值處理
- 資料驗證

功能：自動化報表產生
- 資料聚合
- 圖表生成
- 套用模板
- 多格式輸出（PDF, Excel）

功能：Sprint 規劃助手
- 工作量估算
- 任務優先順序排序
- 產生 Sprint 目標
- 風險識別

功能：會議記錄產生器
- 自動產生會議記錄
- 提取行動項目
- 指派負責人
- 追蹤待辦事項

功能：專案狀態報告
- 進度追蹤
- 風險標記
- 里程碑檢查
- 利害關係人報告

功能：時間追蹤分析
- 時間分布分析
- 生產力報告
- 專案成本計算
- 時間最佳化建議

功能：回顧會議引導
- 產生討論問題
- 整理回饋意見
- 識別改進項目
- 追蹤行動計畫

功能：客服郵件回覆助手
- 自動分類郵件
- 產生回覆範本
- 情緒分析
- 優先順序排序

功能：常見問題產生器
- 從文件提取 FAQ
- 分類和組織
- 產生答案
- 搜尋優化

功能：客服單分析
- 問題分類
- 趨勢分析
- 回應時間追蹤
- 客戶滿意度分析

功能：客戶回饋分析
- 情緒分析
- 主題萃取
- 優先順序排序
- 改進建議產生

功能：知識庫建立器
- 文章結構化
- 標籤和分類
- 搜尋最佳化
- 相關文章連結

---
name: skill-name
description: 詳細說明此 Skill 的功能和使用時機。使用第三人稱，包含關鍵字，說明何時應該使用此 Skill。
version: 1.0.0
author: Your Name
license: MIT
changelog: |
  v1.0.0 (2025-01-01):
    - 初版發布
    - 實作基本功能
---

# Skill 名稱

## 目的

[2-3 句話說明這個 Skill 的用途和價值]

## 使用時機

此 Skill 應該在以下情況使用：
- [情境 1]
- [情境 2]
- [情境 3]

## 快速開始

\`\`\`bash
# 最基本的使用方式
[command example]

# 常用選項
[command with options]
\`\`\`

## 安裝與設定

### 相依套件

\`\`\`bash
# 安裝 Python 套件
pip install -r requirements.txt

# 或使用 npm
npm install
\`\`\`

### 環境變數

\`\`\`bash
# 複製環境變數範本
cp .env.example .env

# 編輯必要的設定
# API_KEY=your-key-here
# API_URL=https://api.example.com
\`\`\`

## 檔案說明

### Scripts

#### scripts/main_script.py
[說明主要腳本的功能]

**用法：**
\`\`\`bash
python scripts/main_script.py --help
\`\`\`

**參數：**
- `--input`: 輸入檔案路徑
- `--output`: 輸出檔案路徑
- `--verbose`: 詳細輸出

**範例：**
\`\`\`bash
python scripts/main_script.py --input data.json --output result.json
\`\`\`

### References

#### references/guide.md
[說明參考文件內容和如何使用]

由於檔案較大，建議使用 grep 搜尋：
\`\`\`bash
grep "關鍵字" references/guide.md
\`\`\`

### Assets

#### assets/template.xyz
[說明素材檔案用途和如何使用]

## 詳細操作指引

### 步驟 1: [標題]

[詳細說明第一步]

\`\`\`bash
# 指令範例
command example
\`\`\`

### 步驟 2: [標題]

[詳細說明第二步]

## 使用範例

### 範例 1: [基本場景]

**需求：**
[描述需求]

**操作：**
\`\`\`bash
[command]
\`\`\`

**預期輸出：**
\`\`\`
[output]
\`\`\`

### 範例 2: [進階場景]

**需求：**
[描述需求]

**操作：**
\`\`\`bash
[command with advanced options]
\`\`\`

## 最佳實踐

### 1. [建議 1]
[詳細說明]

### 2. [建議 2]
[詳細說明]

### 3. [建議 3]
[詳細說明]

## 疑難排解

### 常見問題

#### Q: [問題]
**A:** [答案]

#### Q: [問題]
**A:** [答案]

### 錯誤訊息

#### "Error message 1"
**原因：** [說明原因]
**解決：**
\`\`\`bash
[solution command]
\`\`\`

#### "Error message 2"
**原因：** [說明原因]
**解決：**
\`\`\`bash
[solution command]
\`\`\`

## 進階設定

### [進階功能 1]
[說明和設定方式]

### [進階功能 2]
[說明和設定方式]

## 限制與注意事項

- ⚠️ [限制 1]
- ⚠️ [限制 2]
- ⚠️ [限制 3]

## 更新日誌

詳細的變更記錄請參考 frontmatter 中的 changelog。

## 貢獻

歡迎貢獻改進！請：

1. Fork 此 Skill
2. 建立功能分支
3. 提交變更
4. 發送 Pull Request

## 授權

[授權資訊，例如 MIT License]

## 相關資源

- [相關文件連結]
- [官方網站]
- [GitHub Repository]

## 元數據檢查

- [ ] name 使用小寫和連字號
- [ ] description 詳細且包含使用時機
- [ ] description 使用第三人稱
- [ ] 包含版本號
- [ ] 包含作者資訊

## SKILL.md 檢查

- [ ] 清楚說明 Skill 的目的
- [ ] 說明何時應該使用此 Skill
- [ ] 提供快速開始範例
- [ ] 包含詳細操作指引
- [ ] 參照所有 scripts/references/assets
- [ ] 使用命令式語氣
- [ ] 沒有與 references 重複的內容
- [ ] 包含疑難排解章節

## Scripts 檢查

- [ ] 所有 script 都可執行（chmod +x）
- [ ] 包含 --help 參數
- [ ] 有清楚的錯誤訊息
- [ ] 檢查相依套件
- [ ] 在 SKILL.md 中說明如何使用
- [ ] 包含使用範例

## References 檢查

- [ ] 內容組織良好
- [ ] 大檔案有搜尋指引
- [ ] 與 SKILL.md 沒有重複
- [ ] 格式化清楚（Markdown）
- [ ] 包含實用範例

## Assets 檢查

- [ ] 檔案完整可用
- [ ] 在 SKILL.md 中說明用途
- [ ] 適當的檔案格式
- [ ] 檔案大小合理

## 測試檢查

- [ ] 用實際案例測試過
- [ ] Scripts 執行正常
- [ ] 錯誤處理適當
- [ ] 文件路徑正確

## 打包檢查

- [ ] 資料夾結構正確
- [ ] 可成功打包成 .zip
- [ ] 檔案權限正確
- [ ] 包含必要的 requirements.txt 或 package.json

## 文件檢查

- [ ] README 或 SKILL.md 清楚
- [ ] 包含範例
- [ ] 包含疑難排解
- [ ] 更新日誌完整