⌂ 總覽
Agent Skill 一日工作坊 · 階梯 1

第一次讓 AI 替你動手

說出需求，AI 寫並跑完

11 頁 · 從概念到實作 非工程背景也跟得上 我描述意圖 → Claude 寫 → Claude 跑 → 我拿到結果

需求規格化 · 三大支柱

把需求講清楚：脈絡、範例、驗收標準

01 脈絡 (Context) 業務場景
告訴 AI 這個腳本由誰使用、要處理哪個資料夾裡面的檔案。
✕ 模糊：「幫我整理這堆照片」
✓ 具體：「這是我從 LINE 下載的活動宣傳照片」
02 範例 (Example) 具體對照
給出至少 1 組真實的【整理前 ➔ 整理後】檔名示範，杜絕誤會。
✕ 模糊：「按日期分開並改好名字」
✓ 具體：「IMG_20260801.jpg ➔ /2026-08/001_活動照.jpg」
03 驗收標準 (Criteria) 安全防護
劃定不可越界的防護底線，確保重要資料不被誤刪或覆蓋。
✕ 模糊：「弄好就可以」
✓ 具體：「不要刪除原始檔、遇檔名重複自動加序號流水號」
💬 Claude Code 對話視窗
● CONTEXT APPLIED
👤 你輸入的指令：
「我在工作資料夾下放了從 LINE 下載的活動宣傳照片，請幫我寫腳本整理。」
🤖 AI 理解與執行成果：
已精準鎖定活動照片資料夾，只處理圖片與影片檔，絕不影響其他工作檔案！
  • ✓ 來源鎖定：僅掃描指定的活動照片資料夾
  • ✓ 格式相容：自動支援 .jpg / .png / .mp4
向 Claude Code 交代需求...
三位一體

① 脈絡 Context：給出業務背景，AI 才能精準鎖定目標資料夾與格式。

● SPEC 01: CONTEXT

通用最小範例 · 一起動手

一起做第一個：把下載那堆亂檔，交給它整理

01 建立工作目錄 準備工作
在上一章的工作資料夾底下，建立一個名為「檔案分類」的子資料夾。
📁 路徑：~/workshop/檔案分類/
02 放入小樣本檔案 安全先行
從個人電腦的「下載」資料夾挑選 20 到 30 個檔案拉進去測試。
🛡️ 先跑小樣本確認邏輯，對了再處理整批
03 發送結構化指令 核心關鍵
整合「脈絡、規則、範例」，並加上最重要的「然後幫我跑」！
⚡ 包含 4 大關鍵要素，AI 一次做對
💬 Claude Code 指令組裝與預覽
● FOLDER READY
👤 當前步驟指示 / 輸入指令：
📁 本地工作區狀態：~/工作資料夾/檔案分類/ 已成功建立！
🤖 AI 即時狀態與解析：
已確認工作目錄就緒，隨時可放入小樣本檔案開始整理。
  • ✓ 工作目錄：~/工作資料夾/檔案分類/
  • ✓ 狀態：目錄已就緒，等待放入測試檔
我在工作資料夾下開了一個檔案分類資料夾...
實作口訣

① 建立目錄：在工作資料夾下新增「檔案分類」子資料夾，準備接收素材。

● HANDS-ON STEP 01

動手查核 · 拆解黑盒

任務跑完別急著走：叫你的 AI 解釋邏輯

不只看結果，更要看懂過程。一句話叫 AI 用白話文把腳本邏輯拆給你看。

💬 請在對話框輸入這句話：
「請用白話文解釋剛才寫的 organize.py 邏輯：每一步做了什麼、怎麼判斷檔案類型的、有沒有任何誤刪風險？」
✓ 拆解黑盒 ✓ 檢視防呆 ✓ 驗證原意
🔍 1. 流程流向 (Workflow)
它是如何找到目標檔案、如何分流至各子資料夾的？
🏷️ 2. 命名規則 (Naming)
時間排序抓的是建立還是修改時間？流水號怎麼編排？
🛡️ 3. 安全防護 (Safety)
檔案是「搬移」還是「複製」？遇到重名會不會直接覆蓋？

核心心法：你不需要會寫程式語法，但身為負責人，你必須確認 AI 的執行邏輯完全符合業務預期。

實例透視 · 讀懂邏輯

讀懂 AI 的解釋：確認每一步都符合預期

當 AI 把邏輯拆解成白話步驟，你就掌握了隨時調整與優化的主導權。

💬 Claude Code 對話視窗 · 邏輯拆解 ● EXPLANATION RECEIVED
👤 你問：
「請用白話文解釋剛才的 organize.py 做了什麼？」
🤖 Claude 解釋：
這份腳本主要依序執行 4 個動作：
  • 1️⃣ 掃描清單：只讀取『檔案分類』資料夾內檔案，排除隱藏檔。
  • 2️⃣ 類型分流：依副檔名將 .jpg/.png 歸入圖片夾、.pdf 歸入 PDF 夾。
  • 3️⃣ 時間命名：讀取圖片最後修改時間，由舊到新編號為 001_xxx.jpg。
  • 4️⃣ 安全防護：採用安全檢查，遇到重複檔名自動加序號，絕不覆蓋。
💡 從黑盒變白盒
不再盲目相信執行結果，清楚掌握每一步運作細節。
🎯 精準抓出偏差
若分類規則或命名排序不合心意，能一眼看出該改哪一步。
🔄 輕鬆迭代升級
想增加功能時，只需說「把第 2 步加入 .docx 支援」即可完成！

記住：能理解 AI 執行邏輯的人，才能指揮 AI 完成更精準、更複雜的自動化任務。

本地自動化 · 寫跑一條龍

它寫好也跑完：寫腳本 ＋ 跑腳本一條龍

01 寫腳本 (Write)
本機自動生成 organize.py
02 跑腳本 (Run)
終端機自動調用 python3
03 已交付 (Done)
磁碟檔案完美歸位
organize.py · AI 本地撰寫中
# Step 1: Claude Code 自動生成
import os, shutil, glob
for f in glob.glob("~/Downloads/*.jpg"):
d = extract_date(f)
os.makedirs(f"~/Images/{d}", exist_ok=True)
shutil.move(f, f"~/Images/{d}/")
[STATUS] 腳本已寫入本地磁碟 organize.py
terminal · claude_exec.log
> $ claude "幫我依日期整理下載資料夾"
[PLAN] 正在建立 Python 歸檔腳本...
[WRITE] fs.write("organize.py", code) ➔ OK
LOCAL DISK · 檔案目錄狀態 未整理狀態 (3 個零散檔案)
~/Downloads/
  ├── IMG_20240501_01.jpg
  ├── IMG_20240502_02.jpg
  └── IMG_20240503_03.jpg
一條龍閉環

① 寫腳本：Claude Code 自動在專案目錄產生嚴密的 Python 歸檔腳本。

● PIPELINE: SCRIPT WRITTEN

批次驗證 · 腳本重複調用

再丟 20 個檔案進去：叫 AI 直接跑剛才的腳本

寫好的腳本就是你的數位資產。新檔案進來不用重新解釋規則，一句話直接執行。

① 模擬新素材進場 ● 20 個零散新檔
再從「下載」挑選 20 個新檔案（照片、合約 PDF、簡報）直接丟入資料夾。
📂 目標：~/工作資料夾/檔案分類/
💬 ② 你只需對 AI 說一句話（不用重講規則）：
「我又放了 20 個新檔案進去，請直接用剛才的 organize.py 幫我整理。」
⚡ 不用重講規則 ⚡ 1 秒直接調用 ⚡ 確定性執行
terminal · claude_exec.log
● EXECUTED IN 0.12s
> $ bash "python3 organize.py"
[SCAN] 掃描工作目錄... 發現 20 個新檔案
[MOVE] 12 張相片 ➔ 依時間排序命名 026.jpg ~ 037.jpg 移至 /圖片/
[MOVE] 5 份 PDF ➔ 歸入 /PDF/
[MOVE] 3 份文件 ➔ 歸入 /文件/
✔ 20 個檔案已全部歸位完畢（總耗時 0.12 秒）
💡 寫一次，用無限次
腳本已存於本地磁碟，未來有新檔案隨時喚醒。
🎯 規則一致零偏差
嚴格遵循已查核的命名與防呆規則，絕不出錯。
實作心法

程式碼是你的自動化資產：寫好一次，未來丟入檔案只要「一句話」就瞬間搞定！

● PIPELINE: RE-EXECUTED

Agent 底層原理 · 雙核循環

思維躍遷：AI 自己造工具，然後自己用

PHASE 01: INTENT 👤 使用者意圖 (Prompt)
提出自然語言需求
你只需以日常口語說明要達成的目標（例如「整理 500 個下載檔案」），不需要自己寫任何程式碼。
⚖️ 傳統對話 AI vs Agent AI 思維差異
❌ 傳統 AI：試圖在聊天視窗逐行輸出 500 個檔名（token 爆掉、格式混亂、無法碰磁碟）
✅ Agent AI：把你的話轉化為演算法架構，準備現場編寫專屬執行程式！
👤
① 意圖確立
自然語言
⚙️
② 現場造工具
寫入 .py 腳本
🚀
③ 自己用工具
背景調用執行
🎯
④ 沉澱資產
永久隨叫隨用
Claude Code · 意圖接收視窗
● WAITING FOR DISPATCH
# Step 1: 接收人類自然語言意圖
> "幫我把下載資料夾的檔案按類型與時間整理好..."
[ANALYZE] 拆解核心規則：類型分流 + 時間排序 + 防呆流水號
[DECISION] 任務牽涉真實磁碟與批次操作 ➔ 決定現場撰寫 Python 工具！
核心洞察

① 接收意圖：將人類模糊的自然語言需求，精準轉化為程式邏輯規格。

● DYNAMIC: 01 INTENT RECEIVED

名單清理 · 真實行政情境

清理一份 雜亂的活動報名名單

系統匯出的活動名單：重複報名、大小寫混雜、前後有空格，手動整理要半小時。

你收到的 attendees.csv
王大明,john.doe@gmail.com 王大明, John.doe@GMAIL.com 大小寫不一 王大明,john.doe@gmail.com 前面多一個空格 陳小美,may.chen@company.com 陳小美,may.chen@company.com 一模一樣，重複報名 李志豪,david.lee@service.tw 李志豪,David.Lee@Service.tw 大小寫不一 ... 共 500 行
你說
我有一個 attendees.csv，包含姓名與 Email，但裡面有重複報名、有大小寫不一致、有前後空白。幫我寫一個腳本清理：去掉重複、Email 全部轉小寫、去掉空白，然後按姓名排序，存成 attendees_cleaned.csv。
✓說清楚輸入檔名 ✓三個清理動作 ✓指定輸出檔名

這句話裡有三個動作：去掉重複 → 轉小寫 → 去空白。你不用懂函式，說清楚要什麼，Claude 自己決定怎麼做。

直接開 attendees.csv ↗

名單清理 · 結果

500 筆亂報名資料 → 320 筆乾淨名單，30 秒完成

執行輸出
✔ python3 clean_attendees.py 讀入：500 筆 去空白後：500 筆 轉小寫後：500 筆 去重後：320 筆 排序完成 ✔ 已儲存 attendees_cleaned.csv

輸出的 attendees_cleaned.csv 長這樣：

李志豪,david.lee@service.tw 王大明,john.doe@gmail.com 陳小美,may.chen@company.com ... 共 320 行，乾淨、去重、排序 （英數與筆畫排序，這就是「按規則排序」）
時間對比
以前在 Excel 手動做20 分鐘
現在用 Claude30 秒
行有餘力 · 加碼挑戰

做完基本版之後，試試這個：

「讓 Claude 在清理完之後，加一欄標記每個 Email 的網域名稱（如 gmail.com），存到第三欄。」

這讓你練習「改一個現有腳本」，而不是從零重說。

階梯 1 · 收尾

做完了，每個人都帶走一個成功經驗

恭喜完成第一梯！不用懂程式，你已經掌握讓 AI 替你動手寫跑的核心鏈條。

全員帶走核心能力
✓「意圖 → 腳本 → 執行 → 結果」
這條自動化鏈在腦裡了
✓親眼看過 AI 寫 + 跑
兩件事在本地無縫連在一起
✓用中文說清楚意圖與邊界
比自己動手寫 code 更重要
✓名單清理：20 分鐘 → 30 秒
親身體驗自動化的百倍提速

這一梯最重要的一句話：AI 不只聊天，它能寫出腳本然後直接跑。你的工作是說清楚意圖，剩下的它來。