他在客戶會議上示範自己寫的 AI Agent Skill，數字卻對不起來
會議室裡，林哲安（示意人物，一間中小型會計師事務所的內部系統管理人員，非真實客戶）點開螢幕分享，準備示範他上週末花了一整晚做出來的「月報自動彙整技能」。主管坐在他旁邊，客戶端的窗口也在線上等著看成果。他按下執行，AI Agent 很快就把各分店的數字彙整成一份報表——唯獨最後一欄的合計數字，跟旁邊小計加總起來對不上。
會議室安靜了三秒。主管先開口：「這個…數字是怎麼跑出來的？」林哲安答不出來，因為連他自己都不知道 AI 是怎麼把這幾個數字加起來的。他只知道，這個「技能」是他上週六晚上叫 AI 幫他寫的，寫完看起來像那麼一回事，他就直接拿來用了。
那天晚上他把整套流程重新拆開來看，才發現自己一次踩中好幾個「AI Agent Skill」最容易犯的錯——而且都是一開始看不出來、真正拿去用才會爆出來的那種錯。
他的技能，AI 根本沒點開
林哲安打開他寫的 skill.md 檔案重新檢查，才發現最上面那段 YAML 裡的「description」寫得含糊——大概就是「產生月報彙整」這幾個字。問題是，AI Agent 在啟動時並不會把每一個技能的全文都讀進去，它只會先看每個技能的名稱和描述，靠這幾句話判斷「現在這個情境該不該用它」。描述含糊，Agent 大概率會判斷「好像用得到、好像也用不到」，然後選擇不用，自己臨場現算——這正是他示範失敗的第一層原因：那個技能可能根本沒被觸發，AI 是憑自己的方式現場推算出那份報表的。
他把描述改寫成更明確的版本：清楚寫出「這個技能做什麼」以及「什麼情境該用它」，例如「彙整每月各分店營收明細成月報表，用於使用者要求月報、月結彙整或分店數字彙總時」。他還聽過一個說法：模型天生比較容易「該用而沒用」，所以描述寧可寫得直白一點、甚至稍微「賣力推銷」自己，也不要寫得太保守含蓄。
那份「AI 幫他寫」的技能，其實什麼都沒教
觸發問題解決後，林哲安打開技能本體再讀一次，發現內容大多是「請確認輸入資料正確」「妥善處理錯誤情況」這類放諸四海皆準的空話——這些 AI 本來就知道，寫進技能裡等於沒寫。真正該放進技能裡的，是 AI 自己想不到的「你這裡的特殊做法」：哪一步容易出錯、上次哪裡被主管打回票、老報表裡藏著什麼奇怪的例外規則。
他索性把上個月被主管退回三次的舊報表、當時的修改留言全部翻出來，一條一條把「當時到底錯在哪裡、後來怎麼改對」寫進技能內容裡。這批「踩過的坑」才是這個技能真正值錢的部分——因為那是 AI 自己查不到、只有他這個做過這件事的人才知道的細節。
技能越補越長，AI 反而開始「恍神」
把坑一條一條補進去之後，這份技能檔案越寫越長，長到後來 Agent 執行速度變慢，甚至開始漏看前面交代過的重點。林哲安才理解，技能被選中之後，全文會被整個載入到當下的對話情境裡，跟其他所有正在處理的內容搶同一份注意力額度——寫得越長，等於讓 AI 在做這件事的當下，可用的「思考空間」被自己的說明書擠壓掉一大塊。
解法不是把內容刪回空洞，而是分層：技能本體只留 AI 真的需要、當下用得到的內容，篇幅抓在大約 500 行、換算下來差不多 5,000 個 Token 上下（此為原影片講者的經驗法則，非本站或任何平台的官方換算標準，實際 Token 數會依模型與分詞方式而異）；再細節、不是每次都會用到的補充規則（像是特定分店的例外規定），另外放進一個子資料夾裡，AI 只有在真的碰到那個情境時才會去讀取，不會平白佔用日常執行的額度。這正是林哲安第一次意識到，寫技能其實也是一種要精打細算的 Token 用量規劃，不是寫得越詳細越保險。
那個對不起來的數字，其實不是巧合
回到那天出包的合計問題。林哲安檢查後發現，加總這一步，他原本是讓 AI 自己讀數字、自己心算加起來——而語言模型本質上是在「預測」下一個最可能的答案，不是真的在做四則運算，數字一多、欄位一雜，就容易算錯又算得一臉篤定。
他把「加總」這一步從「請 AI 自己算」改成寫一小段固定的計算邏輯，讓技能直接呼叫這段程式去做加總，AI 不再自己心算，只負責把資料整理好、把運算結果放進報表。那個會在客戶面前出包的合計問題，從此變成不會再出現的一類錯誤——因為對錯不再由 AI 臨場「猜」，而是由一段每次跑起來結果都一樣的邏輯決定。他也發現，這個判斷原則不只適用在算數：任何一步只要「必須每次都精準一致」，就該交給固定邏輯，AI 只需要負責判斷「什麼時候該呼叫它」。
一個「別人已經寫好」的技能檔案，差點被他直接安裝
技能修好、月報也順利跑出正確數字之後，林哲安在同業的 Line 群組裡看到有人分享了一個現成的「發票核銷技能」壓縮檔，附言說「直接丟進去用就對了，很方便」。他一度想直接安裝——反正檔案裡不過就是一些文字說明和幾支腳本，能有什麼問題。
但他想起自己剛才修好的技能，本身就能執行程式碼、能讀寫本機檔案，甚至有機會碰到系統裡設定好的 API 金鑰——換句話說，安裝一個陌生人寫的技能，某種程度上等於直接在自己的環境裡跑一個不認識的人寫的程式。他後來看到，這支介紹技能最佳實踐的影片裡也提到，曾經有人抽查過近四千個公開流通的技能，裡面三成五左右被抓到有某種安全瑕疵，一成三左右藏著更嚴重的問題，像是惡意程式或誘導 AI 做出非預期行為的手法（這個數字是影片講者引用某項稽核的說法，影片中並未進一步指名出處，屬於轉述、非本站或 AITK 獨立查證的數據，僅供風險意識參考，不代表任何具體公開技能庫的實際比例）。
他沒有直接安裝那個壓縮檔，而是先花十分鐘打開裡面的說明和腳本讀過一遍，確認它實際上會碰觸哪些檔案、會不會對外發送任何東西——就像評估一個新的套件要不要放進專案裡一樣。這一次，他把「先讀過再用」變成自己往後對待任何非自己寫的技能的預設動作。
隔週，同一間會議室，他再按下一次執行鍵
隔週的月報示範，林哲安在同一間會議室、同樣的主管和客戶面前，重新按下執行鍵。這一次，合計數字第一次就對上了，畫面上也沒有任何多餘的等待或卡頓。沒有人特別稱讚這件事——一份對的報表本來就不該被稱讚，它本來就該是對的。
但林哲安自己在會議結束後，多做了一件事：他把這幾週踩過的坑，整理成一張團隊共用的「技能上線前檢查清單」，往後任何人要把新技能接上正式流程之前，都得先過這張清單，而不是像他第一次那樣，寫完看起來像那麼一回事，就直接拿去在客戶面前示範。
FAQ
Q1：AI Agent Skill 跟一般的 Prompt（提示詞）有什麼不同？
Prompt 通常是每次對話當下臨時給的指令；Skill 則是一份固定存在、寫成檔案的「工作說明書」，教會 AI 你做某件特定工作的具體方式與眉角，之後不需要重新解釋，AI 在需要時會自己判斷要不要調用它。
Q2：技能檔案是不是寫得越詳細越好？
不是。技能一旦被 Agent 選中執行，整份內容都會佔用當下的處理額度，寫得過長反而會排擠 AI 對其他事情的注意力、拖慢反應。原則是只寫 AI 自己想不到的「你的特殊做法」，非日常會用到的細節則另外拆到補充資料夾，需要時才讀取。
Q3：為什麼 AI 明明看起來很聰明，卻連加總這種小事都會算錯？
因為語言模型本質上是在「預測」最可能的下一個內容，不是真的在執行精確運算。欄位一多、數字一雜，靠 AI 臨場心算就容易出錯。凡是「每次都必須精準一致」的步驟，建議改用固定的程式邏輯來做，AI 只負責判斷什麼時候該呼叫它。
Q4：可以直接安裝別人分享的現成技能檔案嗎？
建議先當成引入一個新的軟體套件來看待：技能檔案可以包含會實際執行的程式碼，可能碰觸本機檔案或系統中設定好的金鑰。安裝前先讀過內容、確認它實際會做什麼，會比「聽起來方便就直接用」安全得多。
Q5：這些做法只適用在 Claude 系列產品嗎？
依原影片說法，技能這種「以資料夾＋說明檔案」呈現的做法，目前有一個跨平台的公開標準（agentskills.io）在推動，影片中也提到 OpenAI Codex 等其他 Agent 平台採用類似的運作方式。這部分屬於影片講者的轉述，本站未獨立查證各平台實際規格是否完全一致，但本文提到的判斷原則（描述要精確、內容要精簡、關鍵步驟不靠 AI 用猜的）屬於通用的工程思維，不限定在單一廠商的工具上。
資料來源聲明
本文參考自 YouTube 頻道「IBM Technology」於 2026 年 8 月 10 日發布的影片《5 Best Practices for Building AI Agent Skills》（講者 Martin Keen、Bri Kopecki），並經重新組織與故事化改寫，非逐字翻譯。文中「林哲安」為說明用示意人物，非真實客戶，其遇到的月報示範情境與各項修正經過均為示意性重新編排，並非任何真實客戶的個案紀錄。文中提及「公開技能安全稽核發現約三成五有安全瑕疵、一成三含嚴重問題」一節，為原影片講者引用某項稽核的說法，影片本身未進一步指名出處，本站未獨立查證，僅作為風險意識參考，不代表任何具體技能庫的實際比例。文中提及的技能檔案結構（skill.md、references、scripts 資料夾）與行數/Token 用量建議，均為原影片內容轉述，實際規範以 agentskills.io 公開標準與各平台官方文件為準。文中「agentskills.io 為跨平台公開標準」「OpenAI Codex 等平台採用類似運作方式」一節，同樣為影片講者轉述，本站未獨立查證各平台實際規格是否完全一致。
延伸閱讀
立即行動
想清楚一個 AI Agent Skill「什麼時候該被觸發、內容該有多少、哪些步驟不該讓 AI 用猜的」，跟想清楚你的 AI 自動化每個月燒掉多少 Token，其實是同一件事——都是先把看不見的用量攤開來看，才知道該怎麼設界線。免費試用 AI Token King，讓我們幫你把團隊每個 Agent、每個 Skill 實際花掉的 Token 用量攤開來看，替你設好屬於團隊的使用邊界。
留言