AgentScope 智能体技能（Agent Skill）指南

一、什么是 Agent Skill？

Agent Skill（智能体技能）是由 Anthropic 提出的一种提升智能体在特定任务上能力的方法。它的核心思想是：

将某个领域的操作指南、脚本和资源打包成一个独立的目录，让智能体在遇到相关任务时，动态加载并按照指令执行。

在 AgentScope 中，Skill 通过 Toolkit 的 register_agent_skill 方法注册。每个 Skill 目录必须包含一个 SKILL.md 文件，其中包含 YAML 前置元数据和操作指令。

Skill 的典型结构

my-skill/
├── SKILL.md          # 必需的：包含技能名称、描述和使用说明
├── scripts/          # 可选的：相关脚本文件
└── resources/        # 可选的：资源文件

其中 SKILL.md 的格式如下：

---
name: token-plan-image
description: 使用 Token Plan 团队版的图像生成模型根据文字描述生成图像。当用户请求生成图片、画图、文生图时触发。
---

# Token Plan 图像生成

当用户请求生成图像时，执行以下操作：

1. 使用 bash 工具运行以下 curl 命令...

二、为什么需要 Skill？

传统的工具函数（Tool Function）需要开发者编写 Python 代码并注册到 Toolkit 中。这种方式虽然灵活，但存在以下问题：

学习成本高：需要理解 AgentScope 的工具函数规范（类型注解、返回 ToolResponse、文档字符串等）
灵活性差：一旦封装成代码，修改工具行为需要重新部署
无法利用 AI 的推理能力：传统工具函数是固定的 API 调用，而 Skill 可以包含复杂的、多步骤的指令，让大模型自行推理和执行

Skill 的优势在于：

零代码注册：只需一个 Markdown 文件即可定义技能
动态加载：智能体可以根据任务需要，自行决定是否使用某个 Skill
可解释性强：Skill 的指令对人类和 AI 都清晰可读
跨平台复用：同一个 Skill 可以在不同智能体之间复用

三、AgentScope Skill 核心 API

AgentScope 通过 Toolkit 类提供了对 Skill 的内置支持：

API	描述
`register_agent_skill(path)`	从指定目录注册智能体技能
`remove_agent_skill(name)`	根据名称移除已注册的技能
`get_agent_skill_prompt()`	获取所有已注册技能的提示词

使用条件

使用 Skill 时，智能体必须配备以下工具之一：

view_text_file（查看文本文件）
execute_shell_command（执行 shell 命令）

因为智能体需要读取 SKILL.md 文件来获取技能指令。

四、实战：在 Coding Plan Agent 中集成图像生成 Skill

下面我们通过一个完整的实战案例，演示如何在 AgentScope 中集成和使用 Skill。

步骤 1：准备 Skill 目录

假设我们已有以下 Skill 目录：

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

SKILL.md 内容如下：

---
name: token-plan-image
description: 使用 Token Plan 团队版的图像生成模型根据文字描述生成图像。当用户请求生成图片、画图、文生图时触发。
---

# Token Plan 图像生成

当用户请求生成图像时，执行以下操作：

1. 使用 bash 工具运行以下 curl 命令...

2. 从返回的 JSON 中提取 `output.choices[*].message.content[*].image` 字段获取图像 URL。
3. 使用 curl 将图像下载到当前目录。
4. 展示图像 URL 和本地文件路径。

步骤 2：注册 Skill 到 Toolkit

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

# 创建 Toolkit
toolkit = Toolkit()

# 注册必备工具（Skill 需要这些工具来读取 SKILL.md）
toolkit.register_tool_function(execute_shell_command)
toolkit.register_tool_function(execute_python_code)
toolkit.register_tool_function(view_text_file)

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

步骤 3：创建 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 自动注入 Skill 提示词

当 ReActAgent 初始化时，它会自动将 Toolkit 中注册的所有 Skill 提示词附加到系统提示词中。最终系统提示词如下：

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 团队版的图像生成模型根据文字描述生成图像。当用户请求生成图片、画图、文生图时触发。
Check "C:\Users\jbcod\Desktop\Skills\token-plan-image/SKILL.md" for how to use this skill

步骤 5：与智能体交互

启动程序后，当用户输入图像生成请求时：

User: 请帮我生成一张夕阳下海滩的风景图

智能体会执行以下流程：

识别需求：用户请求生成图片
匹配 Skill：发现 token-plan-image 技能与当前任务相关
读取 SKILL.md：使用 view_text_file 工具读取技能指令
执行操作：按照 SKILL.md 中的步骤，使用 execute_shell_command 执行 curl 命令调用 API
返回结果：展示生成的图像 URL 和本地文件路径

执行过程

五、Skill vs 传统工具函数对比

特性	传统工具函数	Agent Skill
实现方式	Python 函数	Markdown 文件
注册方式	`register_tool_function`	`register_agent_skill`
灵活性	固定逻辑	大模型按需推理执行
修改成本	需修改代码并重启	修改 SKILL.md 即可
学习门槛	需了解 ToolResponse 等规范	仅需写 Markdown
适用场景	标准化、高频调用	复杂、多步骤、偶尔调用

六、最佳实践

为 Skill 目录使用绝对路径：避免因工作目录变化导致找不到 Skill
SKILL.md 必须包含 YAML 前置元数据：name 和 description 是必须的
确保智能体配备 view_text_file 工具：否则无法读取 SKILL.md
Skill 描述要清晰：描述越清晰，大模型越容易判断何时使用该技能
避免在 Skill 中写入敏感信息：如 API Key，应通过环境变量传递

七、总结

AgentScope 的 Skill 机制为智能体提供了一种声明式的能力扩展方式。相比于传统工具函数，Skill 更适合以下场景：

操作步骤复杂、需要多步推理的任务
需要频繁调整逻辑的工具
非技术团队成员也能维护的工具

通过将 SKILL.md 和 Toolkit 结合，AgentScope 让智能体具备了"阅读说明书并按步骤操作"的能力，这是向更通用、更灵活的 AI Agent 迈进的重要一步。

AgentScope 智能体技能（Agent Skill）指南