一、什么是 Agent Skill？

Agent Skill（智能體技能）是由 Anthropic 提出的一種提升智能體在特定任務(wù)上能力的方法。它的核心思想是：

將某個(gè)領(lǐng)域的操作指南、腳本和資源打包成一個(gè)獨(dú)立的目錄，讓智能體在遇到相關(guān)任務(wù)時(shí)，動(dòng)態(tài)加載并按照指令執(zhí)行。

在 AgentScope 中，Skill 通過(guò) Toolkit 的 register_agent_skill 方法注冊(cè)。每個(gè) Skill 目錄必須包含一個(gè) SKILL.md 文件，其中包含 YAML 前置元數(shù)據(jù)和操作指令。

Skill 的典型結(jié)構(gòu)

my-skill/
├── SKILL.md          # 必需的：包含技能名稱(chēng)、描述和使用說(shuō)明
├── scripts/          # 可選的：相關(guān)腳本文件
└── resources/        # 可選的：資源文件

其中 SKILL.md 的格式如下：

---
name: token-plan-image
description: 使用 Token Plan 團(tuán)隊(duì)版的圖像生成模型根據(jù)文字描述生成圖像。當(dāng)用戶(hù)請(qǐng)求生成圖片、畫(huà)圖、文生圖時(shí)觸發(fā)。
---

# Token Plan 圖像生成

當(dāng)用戶(hù)請(qǐng)求生成圖像時(shí)，執(zhí)行以下操作：

1. 使用 bash 工具運(yùn)行以下 curl 命令...

二、為什么需要 Skill？

傳統(tǒng)的工具函數(shù)（Tool Function）需要開(kāi)發(fā)者編寫(xiě) Python 代碼并注冊(cè)到 Toolkit 中。這種方式雖然靈活，但存在以下問(wèn)題：

1. 學(xué)習(xí)成本高：需要理解 AgentScope 的工具函數(shù)規(guī)范（類(lèi)型注解、返回 ToolResponse、文檔字符串等）
2. 靈活性差：一旦封裝成代碼，修改工具行為需要重新部署
3. 無(wú)法利用 AI 的推理能力：傳統(tǒng)工具函數(shù)是固定的 API 調(diào)用，而 Skill 可以包含復(fù)雜的、多步驟的指令，讓大模型自行推理和執(zhí)行

Skill 的優(yōu)勢(shì)在于：

• 零代碼注冊(cè)：只需一個(gè) Markdown 文件即可定義技能
• 動(dòng)態(tài)加載：智能體可以根據(jù)任務(wù)需要，自行決定是否使用某個(gè) Skill
• 可解釋性強(qiáng)：Skill 的指令對(duì)人類(lèi)和 AI 都清晰可讀
• 跨平臺(tái)復(fù)用：同一個(gè) Skill 可以在不同智能體之間復(fù)用

三、AgentScope Skill 核心 API

AgentScope 通過(guò) Toolkit 類(lèi)提供了對(duì) Skill 的內(nèi)置支持：

使用條件

使用 Skill 時(shí)，智能體必須配備以下工具之一：

• view_text_file（查看文本文件）
• execute_shell_command（執(zhí)行 shell 命令）

因?yàn)橹悄荏w需要讀取 SKILL.md 文件來(lái)獲取技能指令。

四、實(shí)戰(zhàn)：在 Coding Plan Agent 中集成圖像生成 Skill

下面我們通過(guò)一個(gè)完整的實(shí)戰(zhàn)案例，演示如何在 AgentScope 中集成和使用 Skill。

步驟 1：準(zhǔn)備 Skill 目錄

假設(shè)我們已有以下 Skill 目錄：

C:\Users\jbcod\Desktop\Skills\token-plan-image\
└── SKILL.md

SKILL.md 內(nèi)容如下：

---
name: token-plan-image
description: 使用 Token Plan 團(tuán)隊(duì)版的圖像生成模型根據(jù)文字描述生成圖像。當(dāng)用戶(hù)請(qǐng)求生成圖片、畫(huà)圖、文生圖時(shí)觸發(fā)。
---

# Token Plan 圖像生成

當(dāng)用戶(hù)請(qǐng)求生成圖像時(shí)，執(zhí)行以下操作：

1. 使用 bash 工具運(yùn)行以下 curl 命令...

2. 從返回的 JSON 中提取 `output.choices[*].message.content[*].image` 字段獲取圖像 URL。
3. 使用 curl 將圖像下載到當(dāng)前目錄。
4. 展示圖像 URL 和本地文件路徑。

步驟 2：注冊(cè) Skill 到 Toolkit

from agentscope.tool import Toolkit, execute_shell_command, execute_python_code, view_text_file

# 創(chuàng)建 Toolkit
toolkit = Toolkit()

# 注冊(cè)必備工具（Skill 需要這些工具來(lái)讀取 SKILL.md）
toolkit.register_tool_function(execute_shell_command)
toolkit.register_tool_function(execute_python_code)
toolkit.register_tool_function(view_text_file)

# 注冊(cè) Skill
skill_path = r"C:\Users\jbcod\Desktop\Skills\token-plan-image"
toolkit.register_agent_skill(skill_path)

步驟 3：創(chuàng)建 ReActAgent

from agentscope.agent import ReActAgent
from agentscope.formatter import OpenAIChatFormatter
from agentscope.memory import InMemoryMemory
from agentscope.model import OpenAIChatModel

agent = ReActAgent(
    name="CodeAssistant",
    sys_prompt=(
        "You are an expert programming assistant named CodeAssistant. "
        "You help users write, debug, and explain code. "
        "When providing code, always include clear comments and explanations.\n"
        "\n# IMPORTANT\n"
        "- For image generation requests, check your equipped skills and use them."
    ),
    model=OpenAIChatModel(
        model_name="qwen3.6-plus",
        api_key="sk-sp-***************8888",
        stream=True,
        client_args={
            "base_url": "https://coding.dashscope.aliyuncs.com/v1",
        },
    ),
    formatter=OpenAIChatFormatter(),
    toolkit=toolkit,
    memory=InMemoryMemory(),
)

步驟 4：ReActAgent 自動(dòng)注入 Skill 提示詞

當(dāng) ReActAgent 初始化時(shí)，它會(huì)自動(dòng)將 Toolkit 中注冊(cè)的所有 Skill 提示詞附加到系統(tǒng)提示詞中。最終系統(tǒng)提示詞如下：

You are an expert programming assistant named CodeAssistant...

# Agent Skills
The agent skills are a collection of folds of instructions, scripts, and resources that you can load dynamically to improve performance on specialized tasks. Each agent skill has a `SKILL.md` file in its folder that describes how to use the skill. If you want to use a skill, you MUST read its `SKILL.md` file carefully.
## token-plan-image
使用 Token Plan 團(tuán)隊(duì)版的圖像生成模型根據(jù)文字描述生成圖像。當(dāng)用戶(hù)請(qǐng)求生成圖片、畫(huà)圖、文生圖時(shí)觸發(fā)。
Check "C:\Users\jbcod\Desktop\Skills\token-plan-image/SKILL.md" for how to use this skill

步驟 5：與智能體交互

啟動(dòng)程序后，當(dāng)用戶(hù)輸入圖像生成請(qǐng)求時(shí)：

User: 請(qǐng)幫我生成一張夕陽(yáng)下海灘的風(fēng)景圖

智能體會(huì)執(zhí)行以下流程：

1. 識(shí)別需求：用戶(hù)請(qǐng)求生成圖片
2. 匹配 Skill：發(fā)現(xiàn) token-plan-image 技能與當(dāng)前任務(wù)相關(guān)
3. 讀取 SKILL.md：使用 view_text_file 工具讀取技能指令
4. 執(zhí)行操作：按照 SKILL.md 中的步驟，使用 execute_shell_command 執(zhí)行 curl 命令調(diào)用 API
5. 返回結(jié)果：展示生成的圖像 URL 和本地文件路徑
   
   
   
   執(zhí)行過(guò)程

五、Skill vs 傳統(tǒng)工具函數(shù)對(duì)比

六、最佳實(shí)踐

1. 為 Skill 目錄使用絕對(duì)路徑：避免因工作目錄變化導(dǎo)致找不到 Skill
2. SKILL.md 必須包含 YAML 前置元數(shù)據(jù)：name 和 description 是必須的
3. 確保智能體配備 view_text_file 工具：否則無(wú)法讀取 SKILL.md
4. Skill 描述要清晰：描述越清晰，大模型越容易判斷何時(shí)使用該技能
5. 避免在 Skill 中寫(xiě)入敏感信息：如 API Key，應(yīng)通過(guò)環(huán)境變量傳遞

七、總結(jié)

AgentScope 的 Skill 機(jī)制為智能體提供了一種聲明式的能力擴(kuò)展方式。相比于傳統(tǒng)工具函數(shù)，Skill 更適合以下場(chǎng)景：

• 操作步驟復(fù)雜、需要多步推理的任務(wù)
• 需要頻繁調(diào)整邏輯的工具
• 非技術(shù)團(tuán)隊(duì)成員也能維護(hù)的工具

通過(guò)將 SKILL.md 和 Toolkit 結(jié)合，AgentScope 讓智能體具備了"閱讀說(shuō)明書(shū)并按步驟操作"的能力，這是向更通用、更靈活的 AI Agent 邁進(jìn)的重要一步。