建立使用 Skill 的 Agent

Skill 是一個包含 SKILL.md 指示檔，以及可選資源或腳本的目錄。它會告訴 Agent 何時以及如何使用某項能力。

開始前準備

建立並啟用虛擬環境，再安裝 akasha：

uv venv --python 3.11

# macOS / Linux
source .venv/bin/activate

# Windows PowerShell
# .venv\Scripts\Activate.ps1

uv pip install "akasha-terminal[light]"

本範例使用 Gemini。請在執行 Python 的同一個終端機設定 key：

$env:GEMINI_API_KEY = "your_key"

1. 建立 Skill 目錄

在 Python 程式旁建立以下結構：

hello-skill/
├─ SKILL.md
└─ scripts/
   └─ greet.py

建立 hello-skill/SKILL.md：

---
name: hello-skill
description: Generate a deterministic greeting with a bundled script.
---

# Hello Skill

Use this skill when the user asks you to greet someone.

1. Execute the bundled Python script at `scripts/greet.py`.
2. Pass exactly one name as its argument.
3. Return the script stdout as the final answer.
4. If it fails, report the exit code and stderr.

建立 hello-skill/scripts/greet.py：

import sys


def main() -> None:
    name = sys.argv[1] if len(sys.argv) > 1 else "friend"
    print(f"Hello, {name}! This greeting was generated by the Skill script.")


if __name__ == "__main__":
    main()

2. 將 Skill 載入 Agent

在包含 hello-skill 的資料夾建立 skill_agent.py：

from pathlib import Path

import akasha


skill_path = Path("hello-skill").resolve()

agent = akasha.agents(
    model="gemini:gemini-2.5-flash",
    skills=[str(skill_path)],
    stream=False,
)

answer = agent(
    "請使用 hello-skill 向 Alice 打招呼，遵循 Skill 指示並回傳腳本輸出。"
)
print(answer)

執行：

python skill_agent.py

Agent 會讀取 Skill 指示、找到內含腳本，並遵循宣告的工作流程。Skill 不是 Tool 的替代品：Skill 提供指示與資源，Tool 則提供可呼叫的操作。

常見問題

• 找不到 GEMINI_API_KEY：在執行 Python 的同一個終端機設定環境變數。
• 找不到 Skill：確認 hello-skill/SKILL.md 存在，並改用絕對路徑。
• 腳本執行失敗：直接執行 python hello-skill/scripts/greet.py Alice 並查看錯誤。
• Skill 沒有被使用：讓 Skill 描述更具體，並在 SKILL.md 明確寫出必要流程。

如果要直接呼叫具型別的 Python 函式，請閱讀建立 Agent 與使用工具；如果要使用 MCP 工具，請閱讀 MCP。