B.4 Skills 技能擴充:教 Antigravity 學會外貿關稅試算與數據分析
學完本節,你能夠:
- 說明 Skill 與「每次貼一段 Prompt」的差別,以及 Agent 如何決定何時載入 Skill。
- 建立一個包含
SKILL.md與計算腳本的 Skill 資料夾,並寫出能精準觸發的description。 - 用測試輸入驗證 Skill 的計算結果與防呆機制(資料有誤就停止,不用預設值)。
壹、開場情境:同一段規則,貼了第 30 次
📌 以下為教學情境(依實務改編)。
小陳在一家穿戴裝置出口商負責歐洲報價。每次客戶問「到岸成本多少」,他就把一段 800 字的試算規則貼進對話框:先算 CIF、再算關稅、增值稅另列、碼頭費要攤到每台……
某天同事小美幫忙報價,用的是她自己記得的版本:她把增值稅也算進成本。結果同一批貨,兩人報給客戶的到岸成本每台差了約 9 美元,客戶直接來信問:「你們到底哪個數字是對的?」
問題不在 AI 算錯,而在公司的試算規則只存在個人的筆記裡,每個人貼的版本不一樣。
本節要解決的問題: 能不能把公司的試算規則「封裝」一次,讓每個人、每次對話都用同一套規則和同一支計算程式?
貳、概念:Skill 是什麼
1. 定義
Skill(技能包) 是一個資料夾,裡面至少有一個 SKILL.md,可以再附上腳本、參考文件與範例。Antigravity 依官方文件的運作方式是:
- 平常只讀取每個 Skill 開頭的名稱與描述(很短,幾乎不佔空間);
- 當你的要求和某個 Skill 的
description語意相符時,才把完整說明與腳本載入; - Agent 依說明執行,需要精確計算時呼叫腳本。
這種「先看目錄、需要時才翻內文」的做法稱為漸進式揭露(progressive disclosure),好處是可以裝很多 Skill,而不會把 AI 的上下文塞滿。(上下文的概念見第 7.2 節。)
Skill 可以放在兩個層級:專案層級(放在專案資料夾內,只對該專案生效,例如 .agents/skills/)與全域層級(放在使用者設定目錄,所有專案共用)。確切路徑曾隨版本調整,請以官方文件為準。
這批手環到漢堡的
到岸成本?"] --> M{"比對所有 Skill 的
description"} M -->|符合| L["載入 SKILL.md 全文"] M -->|都不符合| N["一般回答,不載入"] L --> S["執行 scripts/calculate_landed.py"] S --> R["回報結果與計算依據"]
2. 每次貼 Prompt vs. 封裝成 Skill
| 面向 | 每次貼 Prompt | 封裝成 Skill |
|---|---|---|
| 一致性 | 每人貼的版本可能不同 | 全團隊用同一份規則 |
| 計算 | 由語言模型直接算,可能算錯 | 交給腳本計算,同樣輸入得到同樣結果 |
| 版本管理 | 散落在個人筆記 | 資料夾可放進 Git 追蹤誰改了什麼(附錄 A) |
| 人員異動 | 離職就帶走 | 留在公司的專案資料夾中 |
這就是第 3.4 節 DRY(Don't Repeat Yourself,不要重複) 原則在 AI 時代的版本:不要重複貼同一段 Prompt。
參、把規則寫下來:到岸成本規格
先把小陳腦中的規則寫成規格表,再寫成 Skill。
| 說法 | 追問 | 規格 |
|---|---|---|
| 「先算 CIF」 | CIF 包含什麼? | CIF = FOB 貨價 + 國際運費 + 保險費 |
| 「再算關稅」 | 稅基是什麼? | 關稅 = CIF × 關稅稅率(以歐盟為例,完稅價格採 CIF 基礎) |
| 「增值稅另列」 | 要不要算進成本? | 進口增值稅單獨列出,不計入到岸成本(進口商通常可申報進項抵扣) |
| 「碼頭費攤到每台」 | 還有其他費用嗎? | 到岸成本 = CIF + 關稅 + 碼頭處理費 + 報關手續費,最後除以數量 |
| (沒說) | 稅率寫成 2.5 是 2.5% 還是 250%? |
稅率必須是 0~1 的小數,或帶 % 的字串;其他寫法一律報錯 |
| (沒說) | 缺欄位、數量為 0 怎麼辦? | 停止並說明原因,不得用預設值代替 |
CIF = FOB 單價 × 數量 + 運費 + 保險費
關稅 = CIF × 關稅稅率
進口增值稅 = (CIF + 關稅) × 增值稅率 ← 教學簡化版稅基,單獨列示
到岸成本 = CIF + 關稅 + 碼頭處理費 + 報關手續費
每台到岸成本 = 到岸成本 ÷ 數量
⚠️ 各國規則不同:例如美國的完稅價格以成交價格(大致接近 FOB)為基礎,不含國際運費。本節以歐盟為例;真正使用時,國別差異應放在
references/中分國說明。
肆、讓 AI 做出來:建立 Skill
1. 資料夾結構
cross-border-tariff-analyzer/
├── SKILL.md # 必備:名稱、描述、使用說明
├── scripts/
│ └── calculate_landed.py # 確定性的計算腳本
└── references/
└── country_notes.md # 各國特殊規則,需要時才讀
2. SKILL.md
開頭的 YAML 區塊(frontmatter)中,description 是必填,Agent 靠它判斷要不要載入;name 使用小寫英文與連字號。
---
name: cross-border-tariff-analyzer
description: 試算進口到岸成本(Landed Cost)、進口關稅與進口增值稅。當使用者詢問 CIF、FOB 換算到岸成本、進口關稅或增值稅試算時使用。不用於:一般海運知識問答、港口介紹、文案潤飾。
---
# 到岸成本試算
## 計算規則
1. CIF = FOB 單價 × 數量 + 運費 + 保險費
2. 關稅 = CIF × 關稅稅率
3. 進口增值稅 = (CIF + 關稅) × 增值稅率,單獨列示,不計入到岸成本
4. 到岸成本 = CIF + 關稅 + 碼頭處理費 + 報關手續費;每台成本 = 到岸成本 ÷ 數量
## 執行方式
- 一律呼叫 `scripts/calculate_landed.py` 計算,不要在對話中自行心算。
- 把使用者提供的數字整理成 JSON 陣列傳給腳本;使用者沒提供的欄位要先問,不要自行假設。
- 腳本回傳錯誤時,把錯誤原因告訴使用者並停止,不要改用估計值。
## 輸出
- 列出每台 CIF、關稅、增值稅、到岸成本(小數兩位),並註明增值稅不計入成本。
- 目的國不是歐盟時,先讀 `references/country_notes.md`。
3. 計算腳本 scripts/calculate_landed.py
只用 Python 內建套件,不需要另外安裝;資料有誤時整批停止並說明原因。
# scripts/calculate_landed.py
# 用途:試算進口到岸成本(Landed Cost),輸入與輸出皆為 JSON。
# 用法:python calculate_landed.py '<JSON 字串>'
import sys
import json
# 必填欄位(金額單位一律為同一幣別,例如 USD)
REQUIRED = ["sku", "quantity", "fob_unit", "freight_total", "insurance_total",
"tariff_rate", "vat_rate", "port_fees_total", "broker_fee_total"]
def parse_rate(value, field):
"""稅率一律轉成小數。'2.5%' → 0.025;0.025 → 0.025。
數字大於 1(例如 2.5)意義不明確,直接報錯,不自行猜測。"""
if isinstance(value, str) and value.strip().endswith("%"):
value = float(value.strip()[:-1]) / 100
value = float(value)
if not 0 <= value < 1:
raise ValueError(f"{field} 應為 0~1 的小數或帶 % 的字串,收到 {value}")
return value
def compute(item):
# 例外 1:缺欄位就停止,不使用預設值
missing = [k for k in REQUIRED if k not in item or item[k] in ("", None)]
if missing:
raise ValueError(f"{item.get('sku', '?')} 缺少欄位:{', '.join(missing)}")
qty = int(item["quantity"])
# 例外 2:數量與金額必須合理
if qty <= 0:
raise ValueError(f"{item['sku']} 數量必須大於 0")
money_fields = ["fob_unit", "freight_total", "insurance_total",
"port_fees_total", "broker_fee_total"]
for k in money_fields:
if float(item[k]) < 0:
raise ValueError(f"{item['sku']} 的 {k} 不可為負數")
tariff = parse_rate(item["tariff_rate"], "tariff_rate")
vat = parse_rate(item["vat_rate"], "vat_rate")
# 整批計算,最後才除以數量,避免逐台四捨五入的誤差累積
fob = float(item["fob_unit"]) * qty
cif = fob + float(item["freight_total"]) + float(item["insurance_total"])
duty = cif * tariff # 關稅 = 完稅價格 × 稅率
vat_amount = (cif + duty) * vat # 進口增值稅(教學簡化版稅基)
landed = cif + duty + float(item["port_fees_total"]) + float(item["broker_fee_total"])
return {
"sku": item["sku"],
"cif_per_unit": round(cif / qty, 2),
"duty_per_unit": round(duty / qty, 2),
"vat_per_unit": round(vat_amount / qty, 2), # 可申報進項抵扣,不計入成本
"landed_per_unit": round(landed / qty, 2),
}
if __name__ == "__main__":
try:
items = json.loads(sys.argv[1])
results = [compute(it) for it in items]
except (IndexError, json.JSONDecodeError):
print("錯誤:請以 JSON 字串作為第一個參數", file=sys.stderr)
sys.exit(1)
except ValueError as e:
# fail-safe:任何一筆有問題就整批停止,並清楚說明原因
print(f"錯誤:{e}", file=sys.stderr)
sys.exit(1)
print(json.dumps(results, ensure_ascii=False, indent=2))
🔍 驗收重點(不懂語法也能檢查) - 增值稅(
vat_amount)有沒有被加進landed?不應該。 - 是不是整批算完才除以數量?逐台四捨五入再相加,誤差會累積。 - 缺欄位或稅率寫成2.5時,是停止並報錯,還是偷偷用預設值繼續?
伍、跑跑看、壞給你看
把 Skill 資料夾放進專案後,在對話框輸入:
「我們要出 2,000 台智慧手環到漢堡港,FOB 單價 45 美元,整批海運費 3,200 美元、保險費 180 美元,關稅 2.5%,增值稅 19%,碼頭處理費 400 美元,沒有報關手續費。請試算每台到岸成本。」
Agent 應該載入 cross-border-tariff-analyzer,把數字整理成 JSON 交給腳本,得到:
| 項目 | 整批(USD) | 每台(USD) |
|---|---|---|
| CIF | 93,380.00 | 46.69 |
| 關稅(2.5%) | 2,334.50 | 1.17 |
| 碼頭處理費 | 400.00 | 0.20 |
| 到岸成本 | 96,114.50 | 48.06 |
| 進口增值稅(19%,不計入成本) | 18,185.76 | 9.09 |
開場小美的報價,就是把 9.09 美元的增值稅也算進成本,才會和小陳差了約 9 美元。
| 實驗 | 操作 | 預期結果 | 想想看 |
|---|---|---|---|
| ① 加報關費 | 報關手續費改為 300 美元 | 每台到岸成本變為 48.21 | 為什麼 CIF、關稅都沒變? |
| ② 稅率寫錯 | 關稅寫成 2.5(沒有 %) |
腳本報錯:稅率應為 0~1 的小數或帶 % 的字串,整批停止 | 如果腳本自己猜成 2.5%,哪天猜錯會怎樣? |
| ③ 漏資料 | 不提供保險費 | Agent 先追問;若直接執行,腳本回報「缺少欄位:insurance_total」 | 保險費能不能「預設為 0」?誰有權決定? |
| ④ 誤觸發 | 問「漢堡港有什麼歷史?」 | 不載入此 Skill,一般回答 | description 裡的「不用於」發揮了什麼作用? |
陸、寫好 Skill 的五個原則
開源社群 Datawhale 的《Hello-Agents》教學專案中有一篇〈如何寫出好的 Skill〉(GitHub 連結),整理其重點並套用到本例:
| 原則 | 說明 | 本例的做法 |
|---|---|---|
| ① 描述要能精準觸發 | description 是 Agent 唯一先看到的內容;太模糊會漏觸發,太廣會誤觸發 |
寫明「何時使用」與「不用於」 |
| ② 只寫 AI 不知道的事 | 每一句都佔上下文空間;通用常識不必寫 | 只寫公司規則:增值稅不計入成本、缺資料要停止 |
| ③ 分層載入 | 描述(一直載入)→ SKILL.md 本文(觸發時載入)→ 附屬檔案(需要時才讀) | 各國特例放 references/ |
| ④ 精確的事交給腳本 | 格式嚴格、不容出錯的計算用腳本;需要判斷與文字的部分用說明 | 稅費計算交給 calculate_landed.py |
| ⑤ 用明確指令與禁止事項 | 寫「一律呼叫腳本」「不要自行假設」,比寫「請盡量準確」有效 | 執行方式三條都是祈使句 |
柒、回到情境
小陳把 Skill 放進公司共用的專案資料夾並用 Git 管理之後,小美再問到岸成本,Agent 載入的是同一份規則、跑的是同一支腳本,增值稅不會再被算進成本。
| 限制 | 後果 | 在哪裡處理 |
|---|---|---|
| 稅率仍由使用者口頭提供 | 稅率給錯,結果就錯 | B.5 用 MCP 連到稅率資料表或試算表 |
誰都能修改 SKILL.md |
規則被私下改掉 | 附錄 A Git 版本紀錄;第 9 章 權限隔離 |
| 增值稅稅基為教學簡化版 | 實際申報可能有差異 | 由報關行或會計確認後寫入 references/ |
| Skill 數量一多,描述可能重疊 | 挑錯 Skill | 定期檢查各 Skill 的 description 是否互斥 |
本節小結
- Skill = 一個資料夾:
SKILL.md(名稱、描述、說明)+ 選用的腳本與參考檔;Agent 先看描述,相符才載入全文。 description決定觸發精準度,要寫「何時用」也要寫「何時不用」。- 需要精確的計算交給腳本;資料有誤時停止並說明原因,不用預設值繼續。
- 把規則封裝成 Skill,等於把個人經驗變成公司共用、可追蹤版本的資產。
捌、練習
- 改數字(5 分鐘):如果關稅改為 4%,每台的關稅、增值稅與到岸成本各是多少?(提示:用腳本跑,答案應為 1.87、9.23、48.76。)
- 加功能(20 分鐘):請 Agent 修改 Skill,讓輸出多一欄「建議報價」:到岸成本 ÷ (1 − 目標毛利率),目標毛利率 20%。先改
SKILL.md的規格,再讓 Agent 改腳本,最後用本節的範例驗算。(毛利率公式見第 1.1 節。) - 管理反思(討論):公司累積了 50 個 Skill,誰應該負責審核新 Skill 上線?如果業務部私下改了關稅 Skill,造成報價錯誤,責任該怎麼歸屬?