# 用 Claude Code 打造專屬截圖工具：說「我截圖給你看」就能讓 AI 看到畫面

> 原本需要：截圖 → 另存新檔 → 告訴 Claude 路徑 → 才能看到
> 現在只需要：說「我截圖給你看」→ 切換視窗 → 框選 → 標記重點 → Claude 立刻看到並理解

---

## 背景與動機

在用 Claude Code 開發專案時，常常遇到「文字說不清楚，需要截圖說明」的情況。但把截圖分享給 Claude 的流程很繁瑣，大大降低了開發效率。

這篇文章會帶你從零開始，用 **Claude Code 輔助開發**一個截圖工具，建置完成後只要一句話就能讓 Claude 看到你的畫面。

---

## 先搞懂：Command 和 Skill 的差別

在開始建置之前，需要了解 Claude Code 兩種擴充機制的差異，這是本工具選用 Skill 的原因：

| | Command（指令） | Skill（技能） |
|---|---|---|
| 存放位置 | `~/.claude/commands/名稱.md` | `~/.claude/skills/名稱/SKILL.md` |
| 觸發方式 | 使用者手動輸入 `/名稱` | Claude 根據 description **自動判斷**觸發 |
| 適用場景 | 明確的操作指令（如 `/commit`、`/紀錄`） | 需要 AI 自動辨識意圖的場景 |

截圖工具的使用情境是「使用者說一句話，Claude 自動觸發」，所以應該做成 **Skill**，而不是 Command。

---

## 環境需求

- Windows 10 / 11
- [Python 3.x](https://www.python.org/downloads/)（安裝時勾選「Add to PATH」）
- [Claude Code](https://claude.ai/download)（Anthropic 官方 CLI 工具）
- Pillow 套件（安裝指令：`pip install Pillow`）

---

## 整體架構邏輯

這個工具由**三個部分**組成：

┌─────────────────────────────────────────────┐
│              使用者說「我截圖給你看」           │
└───────────────────┬─────────────────────────┘
                    │ Claude 自動比對 Skill description
                    ▼
┌─────────────────────────────────────────────┐
│     SKILL.md（Claude Code Skill）            │
│     → description 觸發詞匹配                 │
│     → 內容指示 Claude 如何執行               │
└───────────────────┬─────────────────────────┘
                    │ Bash 執行（傳入當前專案路徑）
                    ▼
┌─────────────────────────────────────────────┐
│     screenshot_tool.py（核心程式）            │
│     ① 倒數 10 秒視窗 → 使用者切換到目標頁面   │
│     ② 全螢幕暗化 → 拖曳框選                  │
│     ③ 標記編輯器 → 畫筆/箭頭/文字標註重點     │
│     ④ 按「完成」→ 儲存截圖                    │
│        檔名：專案名稱_時間戳.png               │
│     → 輸出檔案路徑給 Claude                   │
└───────────────────┬─────────────────────────┘
                    │ Read 工具讀取圖片
                    ▼
┌─────────────────────────────────────────────┐
│     Claude 看到截圖，智慧判讀：               │
│     → 圖上有文字標記？優先讀取並回應          │
│     → 有箭頭/圈選？結合上下文判斷意圖        │
│     → 無標記或意圖不明？詢問使用者            │
└─────────────────────────────────────────────┘

**關鍵差異**：不需要在 CLAUDE.md 寫觸發規則。Skill 的 YAML frontmatter 中的 `description` 欄位本身就告訴 Claude 何時該觸發，Claude 會自動比對使用者的語句。

---

## 建置步驟

### 步驟一：建立專案資料夾

在你的電腦上建立一個資料夾，例如：

C:\Projects\claude截圖工具\

### 步驟二：把提示語貼給 Claude Code

剩下的所有事情，都交給 Claude Code 完成。把下面整段提示語複製，貼到 Claude Code 的對話中：

請幫我建置一個「截圖工具」，讓我在開發時可以方便截圖給你看。

【開始建置前，請先按順序做這兩件事】

第一步：執行 Bash 指令取得我的使用者資料夾路徑：
echo $USERPROFILE

第二步：用 AskUserQuestion 工具問我這一個問題：
「請問你想把截圖工具的程式檔案安裝在哪個資料夾？
（範例：C:\Projects\claude截圖工具）
截圖會自動存到這個資料夾下的『截圖』子資料夾。」

確認我的回答後，才開始建置所有檔案。

【工具功能需求】
- 我說「我截圖給你看」，你就自動觸發截圖工具
- 程式先出現倒數視窗（10秒），讓我有時間切換到要截圖的頁面，可點按鈕立即開始
- 倒數結束後畫面變暗，我拖曳滑鼠框選要說明的範圍
- 框選完進入標記模式：可以用畫筆畫圈、拉箭頭、打文字標註重點（6 色可選、支援撤銷）
- 標記完按「完成」存檔，或按「跳過」存原圖
- 截圖檔名格式：當前專案名稱_時間戳.png（專案名稱由執行時自動帶入）
- 不需要安裝額外套件（Python 內建 tkinter + 只需要 Pillow）

【需要建立的三個檔案，所有路徑都依照上面確認的結果填入】

檔案一：[安裝資料夾]\screenshot_tool.py（核心截圖程式）
- 在檔案最上方加入：sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')，避免 Windows 中文路徑亂碼
- 從 sys.argv[1] 取得專案路徑，用 os.path.basename() 取出資料夾名稱當檔名前綴
- 第一步：CountdownDialog 類別，tkinter 小視窗顯示倒數 10 秒，含「立即開始截圖」按鈕，Enter/Space 也可觸發
- 第二步：ScreenSelector 類別，PIL.ImageGrab.grab() 擷取全螢幕，ImageEnhance.Brightness 暗化至 0.5，tkinter 全螢幕視窗（fullscreen、topmost、overrideredirect），Canvas 顯示截圖，滑鼠拖曳即時顯示紅色（#FF4444）選取框
- 第三步：AnnotationEditor 類別，框選完的裁切圖進入標記模式：
  - 工具列：畫筆（自由畫線/圈）、箭頭（拖曳起→終，PIL ImageDraw 繪製含三角形箭頭）、文字（點擊位置彈出輸入框，Enter 提交，PIL ImageFont 描邊繪製）
  - 6 色可選（紅/黃/綠/藍/白/黑），當前工具和顏色高亮顯示
  - 撤銷（Ctrl+Z）：每步操作存 PIL Image 快照，撤銷時回到上一張
  - 完成按鈕 + 跳過按鈕（存原圖）+ ESC 取消
  - 文字輸入框開啟時，全域快捷鍵（Ctrl+Z/Escape/Ctrl+Enter）必須停用，避免衝突
  - Enter 鍵不綁定「完成」（避免打字時誤觸），完成用 Ctrl+Enter 或按鈕
  - 大圖自動縮放顯示（不超過螢幕 85%），標記座標需轉換回原圖尺寸
- print(完整檔案路徑) 輸出供 Claude 捕捉，ESC 或取消倒數則 exit(1)

檔案二：[USERPROFILE]\.claude\skills\截圖\SKILL.md（Claude Code Skill）
YAML frontmatter 格式：
---
name: 截圖
description: 使用者想要截圖給你看，以便更清楚說明問題或畫面狀態。觸發條件：使用者說「截圖給你看」、「我截一下」、「截個圖說明」、「讓我截圖」、「我截圖」，或任何表示要用截圖說明問題的語句。
---
內容：指示 Claude 的執行步驟（pwd 取路徑 → Bash 執行 Python → Read 讀圖 → 智慧判讀回應）
判讀規則：圖上有文字→優先讀取回應，有箭頭/圈選→結合上下文判斷，無標記→問使用者

檔案三：在 [USERPROFILE]\.claude\CLAUDE.md 加入路徑參考段落（不需寫觸發規則，Skill 的 description 已處理觸發）：
  ## 截圖工具
  - Skill 位置：`~/.claude/skills/截圖/SKILL.md`（description 自動觸發，不需手動 `/截圖`）
  - Python 程式：[安裝資料夾]\screenshot_tool.py
  - 截圖存放：[安裝資料夾]\截圖\

【建置完成後】
請執行以下指令做一次快速測試，確認程式能正常啟動：
python -X utf8 "[安裝資料夾]\screenshot_tool.py"

Claude Code 會先問你安裝路徑，然後自動建立所有檔案、設定 Skill、跑測試。你只需要回答問題和核准檔案寫入。

---

## 使用方式

建置完成後，在 **任何 Claude Code 對話**中：

1. 說「我截圖給你看」
2. 小視窗出現倒數，趁這時切換到你要截圖的頁面（或點「立即開始截圖」）
3. 畫面變暗後，用滑鼠拖曳框選要說明的區域
4. 進入標記模式——用畫筆圈重點、拉箭頭指位置、打字說明問題
5. 按「完成」存檔（或「跳過」直接存原圖），Claude 立刻看到截圖
6. 如果你在圖上寫了文字說明，Claude 會直接讀取並回應；沒標記才會問你

**標記操作快捷鍵：**
| 按鍵 | 功能 |
|------|------|
| Ctrl+Z | 撤銷上一步標記 |
| Ctrl+Enter | 完成並存檔 |
| ESC | 取消截圖 |

截圖自動存到 `截圖/` 資料夾，檔名格式：`專案名稱_20260302_143524.png`

---

## 常見問題

**Q：倒數時間不夠，來不及切換視窗？**
A：修改 `screenshot_tool.py` 中 `CountdownDialog.SECONDS = 10` 這行，改成你需要的秒數。

**Q：畫面變暗後點擊沒有反應？**
A：確認 Python 視窗有取得焦點，點一下畫面再試。

**Q：路徑出現亂碼？**
A：確認執行指令有加 `-X utf8` 參數，且程式開頭有 `sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')`。

**Q：提示「找不到 PIL」？**
A：執行 `pip install Pillow` 安裝套件。

**Q：可以用在多螢幕嗎？**
A：目前只截取主螢幕，多螢幕支援可後續擴充。

**Q：標記模式可以不用嗎？**
A：可以，按「跳過」會直接存原圖，不加任何標記。

**Q：標記的文字太小/太大？**
A：修改 `AnnotationEditor.FONT_SIZE = 20` 這行，數字越大文字越大。畫筆粗細改 `PEN_WIDTH`，箭頭改 `ARROW_WIDTH`。

**Q：Skill 和 Command 我搞混了，怎麼判斷？**
A：看觸發方式——需要使用者打 `/指令` 才觸發的用 Command，想讓 Claude 自動判斷觸發的用 Skill。截圖工具是後者。

---

## 技術原理簡介

| 技術 | 用途 |
|------|------|
| `PIL.ImageGrab.grab()` | 擷取全螢幕畫面 |
| `PIL.ImageEnhance.Brightness` | 暗化圖片產生遮罩視覺效果 |
| `PIL.ImageDraw` + `PIL.ImageFont` | 在圖片上繪製標記（畫筆、箭頭、文字描邊） |
| `tkinter` | 全螢幕 GUI、倒數視窗、標記編輯器、滑鼠事件處理 |
| `PIL.ImageTk.PhotoImage` | 將 PIL 圖片顯示在 tkinter Canvas |
| `math.atan2` | 計算箭頭三角形角度 |
| `sys.argv[1]` + `$(pwd)` | 取得當前專案名稱，自動套用到截圖檔名 |
| Claude Code Skill（`SKILL.md`） | YAML description 自動觸發，內容指示 Claude 執行流程 |
| `CLAUDE.md` 路徑參考 | 方便維護時快速定位相關檔案（非觸發規則） |

---

*文章分享自 Claude Code 實際開發經驗，2026 年 3 月（更新：加入標記功能）*