AGENT SKILL 一日工作坊 · 進階單元

從「能用」到「專業」:把 skill 寫穩、寫省、寫對

你已經會做一張會觸發的卡了。這單元再上一層:讓 skill 不偏題、不塞爆、不死掉,外加官方最佳實踐。每招都附一個能直接照抄的範例。

16 頁 · 進階單元 四大主題 · 一頁一招 每頁一個可照抄範例
這單元的承諾:不堆口號,每招都給你一段能複製貼上的真實範例。最後一頁附「升級檢查表」,帶回去掃你的卡。

主題 01 / 04

指揮 AI
不偏離

AI 很聰明,聰明會讓它自作主張。專業 skill 先畫好界線,再放它做事。

禁止條款 + 工具白名單 · 共 2 招

把不准做的事,寫在最前面

先講「不准做什麼」,再講「要做什麼」

AI 常熱心過頭:你只要它整理資料,它順手寫了段程式、又回頭問你三個問題。禁令放最前面,它就直接動手。

照抄範例 · 放在指派任務的開頭
## 嚴格禁止

1. 禁止寫任何程式
2. 只准讀指定的那兩個檔案
3. 只准把結果輸出到 output 資料夾
4. 不准上網、不准改到原始檔案
5. 不准反過來問我更多資訊,請直接完成

如果你想寫程式或自己亂動別的東西,停下來。直接開始任務。

# 給工程同事看的對照:上面這幾條換成工具語言,就是「禁止
# 用 Bash 寫程式、只准用 Read、輸出只走 Write、禁用 WebFetch」。
最後那句是關鍵。「如果你想⋯⋯停下來」先預判它最常見的偏題念頭,當場擋回來,比事後糾正有效得多。

你在 baoyu 看到的「負向防呆」就是這招的應用:把專家踩過的雷,寫成卡裡的禁令。

只准用這幾樣工具

與其列「不准用什麼」,不如圈出「只准用什麼」

禁令列不完,白名單一翻就清楚。當任務「只該」做某幾件事,就把那幾件圈起來,其他一律不碰。

照抄範例 · 把禁止條款換成允許範圍
## 允許範圍

1. 只准讀檔案、寫檔案
2. 只准搬資料、整理格式,不准自己寫程式
3. 只在真的有疑問時才開口問,其餘自己決定

超出允許範圍的操作一律禁止。

# 給工程同事看的對照:這份白名單寫成欄位就是
# allowed-tools: Read, Write(skill 用這個欄位鎖工具)。
一條判斷原則:任務越脆弱,越要用白名單。怎麼做都對的事(寫文案)給方向就好;錯一步就壞掉的事(搬資料、改檔案)就把工具圈死。

主題 02 / 04

不塞爆
context

AI 的注意力像一張桌子,就那麼大。堆越多越分心、越容易漏。專業 skill 的功夫,一半在少放東西上桌。

傳路徑 + 極簡回傳 + 占位符模板 · 共 3 招

給它地址,讓它自己去拿

別把整份檔案貼給它,給絕對路徑叫它自己讀

長文整段貼進指令,那些字就永久佔住桌面。只給路徑,它要用才去讀,桌子留乾淨。

✕ 傳內容(桌子被佔住)

請分析以下這份報告:

「(這裡貼了 8000 字
的完整報告內文⋯⋯
整段塞進指令裡)」

✓ 傳路徑(桌子留乾淨)

請分析這份報告,
檔案在:

/Users/me/runs/
  report-20260617/
  data/report.md

讀完再開始分析。
務必用「絕對路徑」(從 / 開頭那種完整地址)。相對路徑常因 AI 不知道自己站在哪個資料夾而找不到檔。

結果寫檔,只報一行狀態

幹完活把成果寫進檔案,只回一句「我好了」

整份成果原封不動回報,等於又把東西堆回桌上。寫進檔案、只回一行狀態,桌子就省下來。

照抄範例 · 任務結尾這樣寫
# 完成後只回一行 JSON,不要把內容貼回來

成功:{"ok": true, "count": 150, "output": "output/result.md"}
失敗:{"ok": false, "err": "簡短描述"}

# 注意:所有結果已寫進檔案,回報裡不必重複。
差距是數字級的。讓 AI 整份回貼,一次可能多吃 8000 個字的桌面;改成只回這一行,剩下約 50 個字。同一件事,桌子省了九成以上。

模板與資料分開放

{{變數}} 留洞,模板寫一次、資料每次換

每次都把完整指令重抄一遍,又長又容易錯。固定的話寫成模板、會變的地方挖成洞,每次只填洞。

照抄範例 · 模板裡用雙大括號挖洞
# 模板(寫一次,固定不動)
你是分析專家。請處理第 {{batch_id}} / {{batch_count}} 批。
輸入檔在:{{input_path}}
結果寫到:{{output_path}}

# 每次執行只換洞裡的值
{{batch_id}}   → 2
{{input_path}} → runs/abc/batch_2.json
好處兩個:省力,固定的話只寫一遍;不出錯,會變的全集中在那幾個洞,一眼就看到要改哪。

主題 03 / 04

讓 skill
穩不死掉

長流程最怕跑到一半斷掉,前功盡棄。專業 skill 做好兩件保命的事:斷了接得回去,壞了知道壞在哪。

固定回報 + 進度存檔 · 共 2 招(第三招「先備份再覆寫」見 baoyu 負向防呆)

情境 · 一口氣檢查 100 頁網站

長任務的保命兩件事

叫 AI 一口氣檢查 100 頁網站,跑很久。跑到一半斷掉怎麼辦?專業 skill 靠這兩件事撐住。

① 固定回報進度
每頁都用同一種說法回報「這頁過了沒」,主流程一看就懂。
② 進度存檔(中斷能續跑)
把「做到第幾頁」記進一個檔。第 70 頁斷了,下次從 71 頁接。
一句話記住:會報進度、進度存得住。這兩件事到齊,長任務才真的「斷得起、續得回」。
(其實還有第三招「先備份再覆寫」,你在 baoyu 負向防呆③ 已經學過,原理一樣,這裡不重複。)

兩件事之一 · 每一步都用同一種說法回報

每檢查完一頁,都用「同一句格式」回報過了沒

每頁回報的話都不一樣、夾雜雜訊,主流程根本看不懂哪頁過、哪頁掛了。約好「每頁回同一種說法」,它一眼就知道該繼續還是重試。

照抄範例 · 每頁固定這樣回報
# 不管這頁檢查到什麼,回報一律長這樣
過了:{"ok": true, "頁碼": 42, "問題": 0}
掛了:{"ok": false, "頁碼": 43, "原因": "圖片缺 alt 文字"}

# 關鍵:第一個字永遠先講「過了沒」(ok),主流程一眼就懂。
重點不是格式長怎樣,是「每次都長一樣」。第一格永遠先講過了沒,主流程才不用每次重新猜。

兩件事之二 · 記下做到哪,斷了能接回去

把「做到第幾頁」存進一個檔,當這次任務的「進度存檔」

檢查到第 70 頁斷電,沒存檔就得整盤重來,前面 70 頁全白做。每頁更新一個進度檔,AI 讀它一眼就知道從 71 頁接著跑。

照抄範例 · 一個極簡的進度存檔
# 這個檔就記三件事,純文字、人也看得懂
這次在做:五泰官網 SEO 檢查
總共幾頁:100
做到第幾頁:70   (斷在這,下次從 71 接)
它就是電玩的存檔點。斷電、當機、或中途清掉記憶後,AI 讀這個檔就知道「接著從第 71 頁跑」。

主題 04 / 04

官方
最佳實踐

前面是實戰經驗,這段直接搬官方規範來掛保證。description、工具宣告、命名都有官方明文,照著做最安心。

description 公式 + 工具宣告 + 命名 · 共 2 頁

官方掛保證的貼紙寫法

description 公式:做什麼 + 什麼時候用

官方把 description 定位成「選卡成敗的關鍵」,並給了公式:前半句講功能,後半句用「Use when」帶出使用者真會說的情境,一律第三人稱。

✕ 官方點名的反例

Helps with documents

I can help you
process Excel files

太模糊(看不出何時用)+ 用了第一人稱「I」,AI 認不出來。

✓ 官方正例(直接照公式)

Extract text and tables
from PDF files, fill forms.
Use when working with PDF
files or when the user
mentions PDFs or forms.

前半功能、後半 Use when 帶情境,全程第三人稱。

兩條鐵律記住:① 一律第三人稱,寫「這張卡會做什麼」,不要寫「我能幫你⋯⋯」,第一人稱會讓 AI 認不出來。② 上限 1024 字,額度有限,逼你只挑最關鍵的觸發詞。

進階用法 · 真實 frontmatter

在開頭宣告它能用哪些工具,名字依「領域-對象-動作」取

這是 SearchFit 那支 SEO 稽核 agent 真實的開頭,用 tools 列出它只准動的工具。其實 skill 自己也能限制工具,只是欄位叫 allowed-tools

真實範例 · seo-auditor agent 的開頭
---
description: 對網站執行完整 SEO 審核。當使用者要求
  「審核我的網站」「SEO 審核」時,啟用此 agent。
tools:                # ← agent 的工具白名單(skill 用 allowed-tools)
  - Read
  - Glob
  - Grep
  - Bash
  - WebFetch
---
限制工具:skill 用 allowed-tools、agent 用 tools
最小的 skill 只要 namedescription,其他選填。要鎖死「只准用這幾樣」,加上對應欄位就行。兩種都能限制工具,別以為只有 agent 能。
命名:領域-對象-動作
seo-auditkeyword-clustering,小寫、連字號、一看就知道在幹嘛。別叫 helper、utils、tools 這種看不出用途的名字。

上線前對著抄一遍,帶得走

你的上線前 checklist

拿你手上的卡對著這張清單逐條打勾。前四組是實戰心法,最後一組是官方明文的硬規格。

指揮不偏離
☐ 開頭有禁止條款或工具白名單
☐ 越脆弱的任務,工具圈得越死
不塞爆 context
☐ 給絕對路徑,不貼整份內容
☐ 結果寫檔,只回一行狀態
☐ 模板與資料用 {{變數}} 分開
讓 skill 穩
☐ 每一步固定回報過了沒
☐ 進度存檔,中斷能續跑
☐ 覆寫前先寫暫存、再換上去
官方最佳實踐 · 寫法
☐ description=做什麼+Use when,第三人稱
☐ 名字用領域-對象-動作,不叫 helper/utils
官方最佳實踐 · 硬規格
☐ 說明書本體不超過 500 行(超過就拆檔)
☐ 小抄只放一層深,別 A 檔指 B 檔再指 C 檔
☐ 至少寫三句測試:該觸發/可觸發/不該觸發
不必一次到位。第一張卡能做到「指揮不偏離」就很好,其他等卡變複雜再一條條補。專業,是迭代出來的。