B.4 Skills 技能擴充:教 Antigravity 學會外貿關稅試算與數據分析

學完本節,你能夠:

  1. 說明 Skill 與「每次貼一段 Prompt」的差別,以及 Agent 如何決定何時載入 Skill。
  2. 建立一個包含 SKILL.md 與計算腳本的 Skill 資料夾,並寫出能精準觸發的 description。
  3. 用測試輸入驗證 Skill 的計算結果與防呆機制(資料有誤就停止,不用預設值)。

壹、開場情境:同一段規則,貼了第 30 次

📌 以下為教學情境(依實務改編)。

小陳在一家穿戴裝置出口商負責歐洲報價。每次客戶問「到岸成本多少」,他就把一段 800 字的試算規則貼進對話框:先算 CIF、再算關稅、增值稅另列、碼頭費要攤到每台……

某天同事小美幫忙報價,用的是她自己記得的版本:她把增值稅也算進成本。結果同一批貨,兩人報給客戶的到岸成本每台差了約 9 美元,客戶直接來信問:「你們到底哪個數字是對的?」

問題不在 AI 算錯,而在公司的試算規則只存在個人的筆記裡,每個人貼的版本不一樣。

本節要解決的問題: 能不能把公司的試算規則「封裝」一次,讓每個人、每次對話都用同一套規則和同一支計算程式?


貳、概念:Skill 是什麼

1. 定義

Skill(技能包) 是一個資料夾,裡面至少有一個 SKILL.md,可以再附上腳本、參考文件與範例。Antigravity 依官方文件的運作方式是:

  1. 平常只讀取每個 Skill 開頭的名稱與描述(很短,幾乎不佔空間);
  2. 當你的要求和某個 Skill 的 description 語意相符時,才把完整說明與腳本載入;
  3. Agent 依說明執行,需要精確計算時呼叫腳本。

這種「先看目錄、需要時才翻內文」的做法稱為漸進式揭露(progressive disclosure),好處是可以裝很多 Skill,而不會把 AI 的上下文塞滿。(上下文的概念見第 7.2 節。)

Skill 可以放在兩個層級:專案層級(放在專案資料夾內,只對該專案生效,例如 .agents/skills/)與全域層級(放在使用者設定目錄,所有專案共用)。確切路徑曾隨版本調整,請以官方文件為準。

flowchart LR U["使用者:
這批手環到漢堡的
到岸成本?"] --> 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 是否互斥

本節小結

  1. Skill = 一個資料夾:SKILL.md(名稱、描述、說明)+ 選用的腳本與參考檔;Agent 先看描述,相符才載入全文。
  2. description 決定觸發精準度,要寫「何時用」也要寫「何時不用」。
  3. 需要精確的計算交給腳本;資料有誤時停止並說明原因,不用預設值繼續。
  4. 把規則封裝成 Skill,等於把個人經驗變成公司共用、可追蹤版本的資產。

捌、練習

  1. 改數字(5 分鐘):如果關稅改為 4%,每台的關稅、增值稅與到岸成本各是多少?(提示:用腳本跑,答案應為 1.87、9.23、48.76。)
  2. 加功能(20 分鐘):請 Agent 修改 Skill,讓輸出多一欄「建議報價」:到岸成本 ÷ (1 − 目標毛利率),目標毛利率 20%。先改 SKILL.md 的規格,再讓 Agent 改腳本,最後用本節的範例驗算。(毛利率公式見第 1.1 節。)
  3. 管理反思(討論):公司累積了 50 個 Skill,誰應該負責審核新 Skill 上線?如果業務部私下改了關稅 Skill,造成報價錯誤,責任該怎麼歸屬?

國立臺中科技大學 國際貿易系 / 企業管理系 專用教材

《現代軟體工程:商學院的 AI 系統思維與 Agent 實踐》

作者:陳俊智 博士 Dr. Chun-Chih Chen

本書章節架構改編自陳鍾誠教授(金門大學)開源課程《現代軟體工程》(github.com/ccc115a/se,MIT 授權),內容針對商學院全面改寫與擴充。