⌂ 總覽
Agent Skill 一日工作坊 · 進階單元

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

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

封面+15 頁 四大主題 · 一頁一招 每頁一個可照抄範例
01
主題 01 / 04

指揮 AI不偏離

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

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

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

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

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

照抄範例 · 放在指派任務的開頭## 嚴格禁止 1. 禁止寫任何程式 2. 只准讀指定的那兩個檔案 3. 只准把結果輸出到 output 資料夾 4. 不准上網、不准改到原始檔案 5. 不准反過來問我更多資訊,請直接完成 如果你想寫程式或自己亂動別的東西,停下來。 直接開始任務。 # 給工程同事看的對照:上面這幾條換成工具語言, # 就是「禁止用 Bash 寫程式、只准用 Read、 # 輸出只走 Write、禁用 WebFetch」。
最後那句是關鍵
「如果你想⋯⋯停下來」先預判它最常見的偏題念頭,當場擋回來,比事後糾正有效得多。
為什麼先寫禁令
AI 的失控不是能力不足,是太主動。把界線放最前面,它就直接動手、不繞路。
這招的延伸
你在 baoyu 看到的「負向防呆」就是這招:把專家踩過的雷,寫成卡裡的禁令。

只准用這幾樣工具

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

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

照抄範例 · 把禁止條款換成允許範圍## 允許範圍 1. 只准讀檔案、寫檔案 2. 只准搬資料、整理格式,不准自己寫程式 3. 只在真的有疑問時才開口問,其餘自己決定 超出允許範圍的操作一律禁止。 # 給工程同事看的對照:這份白名單寫成欄位, # 就是 allowed-tools: Read, Write # (skill 用這個欄位鎖工具)。
黑名單 vs 白名單
禁止條款是黑名單,壞事永遠列不完。反過來圈出「只准用什麼」,一翻就清楚。
一條判斷原則
任務越脆弱,越要用白名單。怎麼做都對的事給方向就好;錯一步就壞的事就把工具圈死。
兩招怎麼搭
禁止條款管行為,白名單管工具。兩個搭起來,AI 就被框在安全範圍裡。
02
主題 02 / 04

不塞爆context

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

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

給它地址,讓它自己去拿

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

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

✕ 傳內容(桌子被佔住)
請分析以下這份報告: 「(這裡貼了 8000 字 的完整報告內文⋯⋯ 整段塞進指令裡)」
那 8000 字一旦貼進去,後面每一步都得拖著它
✓ 傳路徑(桌子留乾淨)
請分析這份報告,檔案在: /Users/me/runs/ report-20260617/ data/report.md 讀完再開始分析。
要用才去讀,讀完不會一直壓著桌子。
一個務必的提醒
務必用絕對路徑(從 / 開頭那種完整地址)。相對路徑常因 AI 不知道自己站在哪個資料夾而找不到檔。

結果寫檔,只報一行狀態

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

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

照抄範例 · 任務結尾這樣寫# 完成後只回一行 JSON,不要把內容貼回來 成功:{"ok": true, "count": 150, "output": "output/result.md"} 失敗:{"ok": false, "err": "簡短描述"} # 注意:所有結果已寫進檔案, # 回報裡不必重複。
這招跟上一招是一對
進門別把東西堆上桌(傳路徑),出門也別堆(回一行)。兩頭都省。
差距是數字級的
整份回貼一次可能多吃 8000 字桌面;只回這一行剩約 50 字。同一件事,省九成以上。
關鍵那一句
「所有結果已寫進檔案,不必重複。」沒這句,AI 還是會手癢把成果貼回來。

模板與資料分開放

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

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

照抄範例 · 模板裡用雙大括號挖洞# 模板(寫一次,固定不動) 你是分析專家。請處理第 {{batch_id}} / {{batch_count}} 批。 輸入檔在:{{input_path}} 結果寫到:{{output_path}} # 每次執行只換洞裡的值 {{batch_id}} → 2 {{input_path}} → runs/abc/batch_2.json
好處一 · 省力
固定的話只寫一遍,模板本身一個字都不動,每次只換洞裡的值。
好處二 · 不出錯
會變的全集中在那幾個洞,一眼就看到要改哪、不會漏抄。
呼應主題
模板和資料分開,桌上每次只放這次真正要動的那幾個值。
03
主題 03 / 04

讓 skill穩不死掉

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

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

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

長任務的保命兩件事

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


① 固定回報進度

每頁都用同一種說法回報「這頁過了沒」,主流程一看就懂,知道該往下還是重試。

② 進度存檔 · 中斷能續跑

把「做到第幾頁」記進一個檔。第 70 頁斷了,下次從 71 頁接,前面不用重來。


一句話記住:會報進度、進度存得住。這兩件事到齊,長任務才真的「斷得起、續得回」。其實還有第三招「先備份再覆寫」,你在 baoyu 負向防呆③ 已經學過,原理一樣,這裡不重複。

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

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

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

照抄範例 · 每頁固定這樣回報# 不管這頁檢查到什麼,回報一律長這樣 過了:{"ok": true, "頁碼": 42, "問題": 0} 掛了:{"ok": false, "頁碼": 43, "原因": "圖片缺 alt 文字"} # 關鍵:第一個字永遠先講「過了沒」(ok), # 主流程一眼就懂。
重點不是格式長怎樣
是「每次都長一樣」。格式本身不重要,一致性才重要。
第一格永遠先講成敗
主流程不用每次重新猜:過了往下一頁,掛了就重試或停下來報你。
給工程同事的技術版
若這頁用腳本跑,慣例是最後印一行 JSON、exit 0 代表成功、1 代表失敗。學員記觀念就夠。

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

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

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

照抄範例 · 一個極簡的進度存檔# 這個檔就記三件事,純文字、人也看得懂 這次在做:五泰官網 SEO 檢查 總共幾頁:100 做到第幾頁:70 # 斷在這,下次從 71 接
它就是電玩的存檔點
斷電、當機、或中途清掉記憶後,AI 讀這個檔就知道「接著從第 71 頁跑」。
只記三件事
這次在做什麼、總共幾頁、做到第幾頁。純文字、人也讀得懂。
給技術端補一句
實作常叫它 progress.json,也可記每步是完成、進行中還是還沒做。學員記觀念就夠。
04
主題 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 的工具白名單 - Read - Glob - Grep - Bash - WebFetch --- # skill 限制工具用 allowed-tools 欄位
限制工具 · 兩種欄位
skill 用 allowed-tools、agent 用 tools。最小 skill 只要 namedescription,要鎖工具再加欄位。兩種都能限制,別以為只有 agent。
命名 · 領域-對象-動作
seo-auditkeyword-clustering,小寫、連字號、一看就知道在幹嘛。別叫 helperutilstools 這種看不出用途的名字。

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

你的上線前 checklist

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

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