Simple Agent Skills

嘿各位開發者！大家在做 AI 輔助工具時，是不是常覺得很兩難？想要 AI 聰明一點、懂多一點規矩，Token 費用就直接爆表；想省錢把 Prompt 縮短，AI 馬上就變笨給你看。

今天我們就來聊聊 Agent Skill 這個好東西，看看怎麼用這種「漸進式」的架構，解決這個讓人頭痛的問題。我們直接拿一個 Android PR Reviewer 來當例子，手把手帶大家實作一遍！

第一部分：為什麼我們需要「漸進式披露」？

以前暴力塞 System Prompt 的慘況

在還沒有 Agent Skill 這種觀念之前，如果想讓 AI 幫忙 Review Android Code，我們通常只能用「暴力解法」，把所有家規一次梭哈塞進 System Prompt：

“聽好了，你是 Android 大神。你要遵守 Clean Architecture、變數命名要用駝峰式、XML 不准給我 hardcode string、Coroutine 的 Scope 要看仔細、絕對禁止用 findViewById、還有記得參考 MVVM 模式…”

這樣做有兩個超級大的缺點：

Token 直接燒光光：即便我今天只是問一句「Button 怎麼置中？」，AI 也被迫要把上面那一大串幾千字的規範背一遍。這就像只是去超商買個水，卻被迫穿全套西裝一樣，既沒效率又浪費錢！
AI 讀到後面忘前面 (Lost in the Middle)：當你的 Prompt 落落長，模型很容易就會「恍神」，把中間的重要指令當耳邊風，最後審出來的 Code 還是不合規範。

救星來了：Agent Skill 的漸進式披露 (Progressive Disclosure)

Agent Skill 的概念其實很像我們寫程式常用的「Lazy Loading」。簡單說就是：沒用到的東西，先別急著載入！

它把知識庫分成三層，只有在真的「需要」的時候，才把對應的資料拿出來：

層級	什麼時候載入？	內容大概是什麼？	Token 消耗
L1 目錄 (Metadata)	隨時待命	Skill 的名字、簡介	超級省
L2 指令 (Instruction)	確定要用時	Review 的 SOP、規則	還行 (中等)
L3 資源 (Resource)	真的執行時	跑腳本的結果、查閱文件	看情況 (通常很低)

這樣設計的好處顯而易見：平常輕輕鬆鬆，真的要打仗時才火力全開！

第二部分：圖解運作原理 (以 Android Code Reviewer 為例)

我們直接看圖最快。假設今天有個「Android PR Reviewer」Skill，當你丟一段 ViewModel 的 Code 給它檢查時，後台到底發生了什麼事？

下面的時序圖 (Sequence Diagram) 清楚展示了 Agent Runtime (像是 Claude Code) 怎麼在中間當「傳話筒」，幫你協調用戶、檔案跟 LLM，把 Token 省到極致。

sequenceDiagram
    autonumber
    participant User as 用戶 (Android Dev)
    participant Runtime as Agent Runtime
    participant LLM as 模型 (大腦)

    User->>Runtime: "欸，幫我看這個 ViewModel 有沒有 Memory Leak"

    %% 階段一：路由 (L1 Metadata)
    rect rgb(235, 245, 255)
        Note right of Runtime: 1. 路由階段<br/>只給目錄，不給內容
        Runtime->>LLM: 用戶問題 + Skill 清單 (只有名字/簡介)
        LLM->>Runtime: 抓到了！這題要用 "android_pr_reviewer"
    end

    %% 階段二：載入 SOP (L2 Instruction)
    rect rgb(255, 250, 240)
        Note right of Runtime: 2. 載入 SOP<br/>確定要用才去讀 skill.md
        Runtime->>Runtime: 讀取 skill.md 檔案
        Runtime->>LLM: 把完整的 Review 規則餵進去 (這時 Context 才變大)
    end

    %% 階段三：資源調用 (L3 Resource)
    rect rgb(240, 255, 245)
        Note right of Runtime: 3. 資源層 (Script/Ref)<br/>省錢大絕招
        
        LLM->>Runtime: 幫我跑一下 "run_lint.py" 這個腳本
        Note over Runtime: 系統默默執行腳本 (模型看不到 Code，只看結果)
        Runtime->>LLM: 回傳結果 (例如: "Line 45: Context Leaked")
        
        LLM->>Runtime: (選用) 我想查一下 "Architecture_Guide.md"
        Runtime->>LLM: 回傳文件內容
    end

    LLM->>Runtime: 給出最終建議 (重構建議)
    Runtime->>User: 顯示 Review 結果

看圖畫重點：

注意看 步驟 3 之前，模型根本不知道什麼 Clean Architecture 或 MVVM 規則，這時候的 Context 超乾淨！
到了 步驟 7，這是最神奇的地方：模型完全沒有讀取 Python 腳本的原始碼，它只是叫系統去「跑」，然後看結果。這意味著你可以掛一個超複雜的靜態分析工具，卻完全不佔用 Token，是不是很聰明？

第三部分：動手做！Skill 設定與結構

好啦，原理懂了，那實際上要怎麼把這個 Skill 做出來呢？其實很簡單，只要把檔案結構擺好、設定檔寫對就搞定。

1. 檔案要放哪？

通常我們會在專案底下建個 .claude/skills/ 資料夾：

.claude/skills/android_reviewer/
├── SKILL.md               <-- [核心] 所有設定跟 SOP 都在這
├── docs/
│   └── architecture.md    <-- [資源] 公司內部的 MVVM 聖經 (要查再看)
└── scripts/
    └── static_check.py    <-- [資源] 幫忙跑腿的 Python 腳本

2. `SKILL.md` 怎麼寫？

這就是 Skill 的靈魂所在！為了方便解說，我們用 Markdown 將其結構拆解成兩個部分來說明：

---
[Metadata]: 這邊設定 name, description, version
---

[Instruction]: 只有當 AI 決定要用這個 Skill 時才會被載入。這裡是你主要定義 Role (角色) 與 Rules (規則) 的地方。以及有使用到的 Script 和 Reference 的路徑與呼叫方式

[完整範例：全部組合起來]

最後，實際存檔時 SKILL.md 的完整樣貌就是把上面兩個部分接起來，長這樣子（記得檔名存成 SKILL.md 喔）：

---
name: android_code_reviewer
description: 專門用來 Review Android/Kotlin 專案。會檢查 MVVM 架構、Context 洩漏跟 Coroutine Scope 亂用的問題。
version: 1.0.0
---

# 你的角色 (Role)
你是一個資深的 Android 系統開發工程師 (AOSP 等級的那種)。

# 必查重點 (Critical Rules)
1.  **Context 洩漏**：眼睛睜大點，檢查 ViewModel 或 Singleton 有沒有偷藏 Activity/View 的 Context。
2.  **Coroutine Scope**：
    - UI 操作一定要在 `lifecycleScope`。
    - 業務邏輯請愛用 `viewModelScope`。
    - 誰再用 `GlobalScope` 就給我打叉叉。
3.  **舊時代遺毒**：如果看到 XML 用 `findViewById`，請直接標記為重大缺失，叫他改用 ViewBinding。

# 工作流程 (Execution Flow)
1.  先跑 `run_lint` 工具掃描一遍。
2.  如果發現架構怪怪的，再去查 `architecture_doc` 看公司的規範怎麼寫。
3.  最後輸出報告時，直接給我 Kotlin 的修正代碼，不要廢話。

# 工具箱 (Tools)
## 腳本 (Scripts)
- name: run_lint
  description: 執行靜態分析腳本，抓一些常見的低級錯誤。
  command: python3 scripts/static_check.py {file_path}

## 參考文件 (References)
- name: architecture_doc
  path: docs/architecture.md
  description: 公司內部的 Android MVVM 架構白皮書

3. Script 範例 (`static_check.py`)

這個腳本就是負責做髒活的。

import sys

# 這段程式碼模型「看」不到喔！它只會看到 print 出來的結果。
# 這就是省 Token 的秘訣！
def check_file(file_path):
    with open(file_path, 'r') as f:
        content = f.read()

    errors = []
    if "GlobalScope.launch" in content:
        errors.append("Critical: 抓到了！偷用 GlobalScope，請改用 viewModelScope。")
    if "findViewById" in content:
        errors.append("Warning: 還在用 findViewById？現在是 ViewBinding 的時代了！")

    if errors:
        print(f"靜態分析發現 {len(errors)} 個問題：")
        for e in errors:
            print(f"- {e}")
    else:
        print("靜態分析通過，沒發現明顯問題。")

if __name__ == "__main__":
    if len(sys.argv) > 1:
        check_file(sys.argv[1])
    else:
        print("Error: 沒給我檔案路徑是要我檢查什麼啦？")

透過這樣的架構，我們就把一個資深 Android 工程師的腦袋（Instruction）跟手腳（Script）都打包進 Agent Skill 裡了。

這種漸進式披露的設計，不僅讓 AI 更專注在當下的任務，不會被一堆無關的規則干擾，重點是還幫我們省下了大筆的 Token 費用。

對於我們這些做系統層級 App 的開發者來說，準確度跟效率就是生命。現在你有了這個「懂事」又「省錢」的架構，下次做 Code Review 或自動化工具時，別忘了試試看 Agent Skill。把那些繁瑣的檢查交給 Script，把需要智慧判斷的邏輯交給 Instruction，讓 AI 真正成為你的神隊友！