告別重複 Prompt：Agent Skills 如何將 Claude 從聊天機器人升級為「工程師」

每次開啟新的 AI 對話視窗，就得重新複製貼上團隊的代碼規範、API 文檔和業務邏輯。Claude 雖然聰明，卻總是記不住專案裡那些「約定俗成」的規矩。

如果說 Prompt Engineering（提示工程）是教 AI 「怎麼說話」，那麼 Agent Skills（智能體技能）就是教 AI 「怎麼做事」。

最近，隨著 Claude Code CLI 工具的發布，Agent Skills 的概念被推向了前台。這不僅僅是一個新功能，它代表了 AI 使用範式的一次重大轉變：從「對話式交互」轉向「資產化交互」。

本文將帶你跳出官方文檔的枯燥定義，從工程實戰的角度，深度解析 Agent Skills 到底是什麼，以及如何親手打造一個能幫你幹活的「AI 員工」。

為什麼我們需要 Agent Skills？

在深入技術細節之前，我們先解決「為什麼」的問題。我們已經有了 System Prompts（系統提示詞），也有了像 .cursorrules 這樣的專案級規則，為什麼還需要 Agent Skills？

核心痛點在於 上下文窗口（Context Window）的稀缺性 和 任務的複雜度。

1. 上下文污染：如果你把所有的 API 文檔、資料庫結構、代碼規範都塞進 System Prompt，不僅會迅速消耗 Token 預算，還會讓 AI 的注意力分散，導致幻覺（Hallucination）增加。
2. 復用性差：一段優秀的 Prompt 往往躺在某個 Notion 筆記裡，難以在團隊間共享。
3. 缺乏行動力：普通的 Prompt 只能生成文本，無法執行腳本或調用工具。

Agent Skills 的本質，是將「專業知識」與「行為規範」封裝成一個可插拔的模組。它就像是給 AI 安裝了一個「技能包」，AI 平時不需要加載它，只有在遇到特定任務時，才會自動調用。

核心機制：漸進式披露（Progressive Disclosure）

Agent Skills 最聰明的設計在於它的加載機制。它不是一股腦把所有信息丟給 AI，而是分三步走。這在工程上被稱為「漸進式披露」，極大優化了 Token 的使用效率。

層級	階段	AI 的行為	類比
L1	技能發現	僅讀取技能的 name 和 description。	瀏覽圖書館的索引目錄。
L2	指令加載	命中需求後，讀取 SKILL.md 的核心規則。	翻開書本，閱讀目錄和摘要。
L3	資源調用	執行具體任務時，按需讀取腳本或參考文件。	深入閱讀某一章節或查閱附錄圖表。

實際效果是：你可以安裝 100 個技能，但只消耗極少的 Token 用於索引。只有當你說「幫我審查這段 Python 代碼」時，AI 才會去加載 python-reviewer 這個技能的詳細內容。

實戰：打造一個「資深 Python 代碼審查員」

接下來我們實際動手做一個 Skill。

假設你的團隊有嚴格的 Python 命名規範，且要求所有的數據庫操作必須經過一個特定的封裝層。我們不希望每次都提醒 AI，而是做成一個 Skill。

1. 目錄結構

在你的專案根目錄或全局目錄 ~/.claude/skills/ 下建立如下結構：

my-project/.claude/skills/
└── strict-python-reviewer/
    ├── SKILL.md           # 核心大腦
    ├── examples/
    │   └── bad_code.py    # 反面教材
    └── scripts/
        └── lint_check.py  # 自動化檢查腳本

2. 編寫大腦：SKILL.md

這是最關鍵的文件。請注意 Frontmatter（頂部的 YAML 區域）的寫法，這決定了 AI 能否準確「喚醒」這個技能。

---
name: strict-python-reviewer
description: 當用戶請求審查 Python 代碼、提交 Pull Request 或重構代碼時使用此技能。專注於命名規範和數據庫安全。
version: 1.0.0
---

# Strict Python Reviewer Guide

你現在是團隊中的「資深代碼審查員」。你的目標不是讓代碼「能跑」，而是要讓代碼「符合工程標準」。

## 核心指令 (Instructions)

1.  **命名鐵律**：
    - 內部輔助函數 **必須** 以 `_internal_` 開頭（例如 `_internal_calc_tax`）。
    - 全局常量必須大寫，且包含模組前綴。

2.  **數據庫安全**：
    - ❌ 禁止直接使用 `SQLAlchemy` 或原始 SQL。
    - ✅ **必須** 使用 `RepoLayer` 封裝器進行所有數據庫交互。
    - 如果發現違規，請直接給出重構後的代碼示例。

3.  **執行流程**：
    - 首先，指出代碼中的風格違規。
    - 其次，檢查潛在的 SQL 注入風險。
    - 最後，輸出一段符合規範的重構代碼。

## 參考示例 (Examples)

**❌ 錯誤示範：**
```python
def get_user(id):
    return db.session.query(User).get(id)

✅ 正確示範：

from core.db import RepoLayer

def get_user(user_id: int) -> User:
    # 使用封裝層
    return RepoLayer.users.get_by_id(user_id)

自動化檢查

在給出建議前，你可以調用 scripts/lint_check.py 來獲取靜態分析報告。

### 3. 添加工具能力（可選）

Agent Skills 的強大之處在於它可以調用腳本。我們可以放一個簡單的 Python 腳本，讓 Claude 在給出建議前先運行它。

```python
# scripts/lint_check.py
import sys

def check_naming(code_snippet):
    issues = []
    if "def _" in code_snippet and "def _internal_" not in code_snippet:
        issues.append("警告：發現私有函數未遵循 '_internal_' 前綴規範。")
    return issues

if __name__ == "__main__":
    # 模擬接收代碼片段並分析
    # 在實際場景中，這裡可以是調用 pylint 或 flake8
    print("正在運行靜態分析...")
    # ... 實際邏輯

4. 實際體驗

當你配置好這個文件夾後，在 Claude Code 終端輸入：

“幫我看看這段代碼寫得怎麼樣：def _calc_price(id): return db.query(id)”

Claude 的處理流程：

1. 掃描：用戶在問代碼審查 -> 匹配到 strict-python-reviewer。
2. 加載：讀取 SKILL.md。
3. 執行：
   • 發現 _calc_price 違反了 _internal_ 規則。
   • 發現 db.query 違反了 RepoLayer 規則。
4. 輸出：直接給出符合你團隊規範的修改建議，而不是通用的 Python 建議。

Agent Skills vs. 其他工具

這看起來很像 .cursorrules 或者 Custom Instructions，它們有什麼區別？

特性	Agent Skills	.cursorrules / .windsurfrules	Custom Instructions
觸發機制	按需觸發 (AI 決定是否使用)	全局/目錄級 (始終生效)	全局 (始終生效)
適用場景	特定任務（如：發布版本、寫SQL、審計）	項目通用規範（如：使用 TypeScript, Tailwind）	個人偏好（如：回答簡短、不要廢話）
複雜度	高（支持多文件、腳本調用）	中（主要是文本規則）	低（純文本）
可移植性	極高（文件夾即插即用）	依賴於特定編輯器	依賴於帳號設置

最佳實踐建議：

• 將通用的、高頻的規則（如「總是使用 React Hooks」）放在 .cursorrules 中。
• 將專業的、流程化的任務（如「生成符合公司標準的 API 文檔」或「執行數據庫遷移」）封裝為 Agent Skills。

批判性視角：它真的完美嗎？

雖然 Agent Skills 看起來很美好，但在實際落地中，我們也觀察到了一些挑戰：

1. 描述的藝術（SEO for Agents）： 如果你的 description 寫得不好，AI 可能根本不會觸發這個技能。你需要像做 SEO 一樣優化你的技能描述。例如，不要只寫 “Tools”，要寫 “當用戶需要處理 CSV 文件格式轉換時使用此工具”。

2. 維護成本： 代碼在變，規範也在變。如果 SKILL.md 裡的知識過期了（例如依賴庫升級了），AI 就會一本正經地寫出過時的代碼。Skill 本身也需要版本控制和維護。

3. 權限邊界： 當 Skill 包含執行腳本的能力時，安全性變得至關重要。你不會希望一個自動化 Skill 不小心刪除了生產數據庫。務必在 SKILL.md 中明確限制工具的使用範圍。

總結與展望

Agent Skills 標誌著 AI 輔助開發進入了一個新階段：標準化與資產化。

以前，團隊裡的「老鳥」通過 Code Review 口頭傳授經驗；現在，你可以把這些經驗寫成 Markdown，變成一個 Skill。這不僅是給 AI 看的，也是團隊知識庫的一種新型存在形式。

如果你想開始使用 Agent Skills，可以先找出團隊中重複率最高的 3 個痛點任務（比如寫單元測試、寫 Swagger 文檔、Git Commit 規範），為它們編寫簡單的 SKILL.md，然後將 .claude/skills 目錄提交到 Git 倉庫讓全團隊共享這個「AI 外掛大腦」。

未來的軟體工程師，可能有一半的時間在寫代碼，另一半的時間在編寫「教 AI 寫代碼」的 Skills。

---

參考資料：

• Anthropic Engineering: Equipping Agents
• Claude Code Official Documentation
• Agent Skills Standard