Agent Scope Java 2.x 系列【10】技能（Skill）

文章目录

[1. 概述](#1. 概述)
[2. Skill 目录结构](#2. Skill 目录结构)
[3. 工作原理](#3. 工作原理)
[4. 注册 Skill](#4. 注册 Skill)
- [4.1 Builder 直接挂载](#4.1 Builder 直接挂载)
- [4.2 优先级规则](#4.2 优先级规则)
[5. 四种 Skill 来源](#5. 四种 Skill 来源)
[6. SkillFilter ------ 启用/禁用控制](#6. SkillFilter —— 启用/禁用控制)
[7. Skill + ToolGroup：按需披露工具](#7. Skill + ToolGroup：按需披露工具)
[8. Skill 执行脚本：配合 Shell 工具](#8. Skill 执行脚本：配合 Shell 工具)
[9. 完整示例](#9. 完整示例)
[10. Skill vs Tool 对比](#10. Skill vs Tool 对比)

1. 概述

Skill 是基于 Markdown 的指令集，无需写新工具代码 即可拓展 Agent 能力。每个 skill 是一个目录，包含一个带 frontmatter 元数据与详细指令的 SKILL.md 文件。

与 Tool 不同，Skill 不能被直接调用 。Agent 通过内置查看器工具 load_skill_through_path 读取 skill 指令，再用现有 tool 按指令执行。

复制代码

Skill（指令）              Tool（执行）
─────────────             ──────────────
SKILL.md 告诉 Agent        Agent 用已有工具
"做什么、怎么做"      →    "读文件、写文件、跑脚本"完成

2. Skill 目录结构

复制代码

skills/
├── pdf-extractor/
│   ├── SKILL.md              ← 核心：frontmatter 元数据 + 指令
│   ├── references/
│   │   └── guide.md          ← 参考文档（可按路径加载）
│   └── scripts/
│       └── run.py            ← 脚本（需 shell 工具才能执行）
├── code-reviewer/
│   └── SKILL.md
└── data-analysis/
    ├── SKILL.md
    ├── references/
    └── scripts/

SKILL.md 格式

name / description：skill 标识和描述
tool-use：可选，声明 skill 需要的工具权限

markdown 复制代码

---
name: pdf-extractor
description: Extract text and metadata from PDF documents
tool-use: read_write
---

# PDF Extractor Skill

## Overview
This skill enables extracting text and metadata from PDF files.

## Instructions
1. Use `read_file` to open the PDF file
2. Parse the content and extract text
3. If the PDF contains images, use OCR tools to extract text from them
4. Return the extracted text and metadata in JSON format

3. 工作原理

Toolkit 在含 skill 时的注册与查看流程：

复制代码

┌──────────────────────────────────────────────────────┐
│  Builder.build() 时                                    │
│  ┌──────────────────────────────────────────────┐     │
│  │ 1. 扫描所有 skill 来源，收集名称/描述/目录      │     │
│  │ 2. 注册 load_skill_through_path 查看器工具     │     │
│  │    → 放入 "skill-build-in-tools" 组            │     │
│  │ 3. 组装 system prompt 片段：列出可用 skill       │     │
│  └──────────────────────────────────────────────┘     │
│                                                        │
│  Agent 运行时                                          │
│  ┌──────────────────────────────────────────────┐     │
│  │ Agent 看到 system prompt 中的 skill 列表         │     │
│  │ Agent 调用 load_skill_through_path(skillId)     │     │
│  │   ├── 返回 SKILL.md 内容                        │     │
│  │   ├── 激活该 skill 绑定的 tool group（如有）       │     │
│  │   └── Agent 按指令用已有工具执行                  │     │
│  └──────────────────────────────────────────────┘     │
└──────────────────────────────────────────────────────┘

load_skill_through_path 工具：

参数	类型	说明
`skillId`	`string`（枚举）	要加载的 skill ID
`path`	`string`	资源路径。传 `"SKILL.md"` 取指令；或精确资源路径如 `"references/guide.md"`、`"scripts/run.py"`

调用示例：

json 复制代码

{
  "name": "load_skill_through_path",
  "input": { "skillId": "pdf-extractor", "path": "SKILL.md" }
}

返回：SKILL.md 的 markdown 内容。如果 path 不存在，返回错误并列出可用资源路径。

4. 注册 Skill

4.1 Builder 直接挂载

java 复制代码

import io.agentscope.core.skill.repository.FileSystemSkillRepository;

ReActAgent agent = ReActAgent.builder()
    .name("SkillCreator")
    .model(model)
    .toolkit(toolkit)
    .skillRepository(new FileSystemSkillRepository(
        Paths.get("/path/to/skills"), false))  // false = 非懒加载
    .build();

Builder 在 build() 时自动装配 DynamicSkillMiddleware，每次 call() 都会按 skill 来源刷新 prompt 与 tool group。

4.2 优先级规则

多次调用 skillRepository(...) 按调用顺序追加------低 → 高优先级 ，同名 skill 后者覆盖前者。

java 复制代码

// base 优先（低优先级）
.skillRepository(new FileSystemSkillRepository(Paths.get("/shared/skills")))
// user 覆盖（高优先级，同名 skill 以 user 为准）
.skillRepository(new FileSystemSkillRepository(Paths.get("/user/alice/skills")))

需要替换整批用 skillRepositories(List)，关掉自动装配用 dynamicSkillsEnabled(false)。

5. 四种 Skill 来源

来源	类	说明
本地文件系统	`FileSystemSkillRepository`	从磁盘目录扫描 `skills/*/SKILL.md`
Git 仓库	`GitSkillRepository`	从远程 Git 仓库拉取，支持自动同步
Classpath	`ClasspathSkillRepository`	从 Jar 或 classpath 资源加载
Nacos	`NacosSkillRepository`	从 Nacos 配置中心加载（企业版）
MySQL	`MysqlSkillRepository`	MySQL 存储
PostgreSQL	`PostgresSkillRepository`	PostgreSQL 存储

使用示例：

java 复制代码

// 本地文件系统
new FileSystemSkillRepository(Paths.get("./skills"));

// 文件系统 + 懒加载（按需读取 SKILL.md，减少启动扫描）
new FileSystemSkillRepository(Paths.get("./skills"), /* lazy= */ true);

// Git 仓库（自动同步 + 指定分支）
new GitSkillRepository("https://github.com/org/skills-repo.git",
                        Paths.get("/tmp/skills-cache"));

// Classpath（Jar 内 skills/ 目录）
new ClasspathSkillRepository("skills/");

// Nacos
new NacosSkillRepository(aiService, "public");

6. SkillFilter ------ 启用/禁用控制

java 复制代码

SkillFilter.all();                    // 全部启用
SkillFilter.none();                   // 全部禁用
SkillFilter.only("pdf", "review");    // 只启用指定 skill
SkillFilter.except("dangerous");      // 排除指定 skill
SkillFilter.enable("pdf");            // 追加启用（叠加模式）
SkillFilter.disable("review");        // 追加禁用（叠加模式）

ReActAgent agent = ReActAgent.builder()
    .skillRepositories(repos)
    .skillFilter(SkillFilter.except("dangerous-tool"))  // 排除危险 skill
    .build();

7. Skill + ToolGroup：按需披露工具

createSkillToolGroup 把一组 tool 绑定到某个 skill name------Agent 加载该 skill 时 tool group 自动激活，未加载时 tool 不出现在模型 schema 中，减少上下文噪音。

java 复制代码

Toolkit toolkit = new Toolkit();

// 注册数据分析工具
toolkit.registerTool(new AnalysisTools());

// 创建与 skill 绑定的 tool group（初始不激活）
toolkit.createSkillToolGroup(
    "analysis-tools",        // group 名称
    "数据分析工具集",          // 描述
    List.of("run_sql", "generate_chart", "export_csv"),  // tool 名列表
    "data-analysis");        // 绑定的 skill name

ReActAgent agent = ReActAgent.builder()
    .name("SkillAgent")
    .model(model)
    .toolkit(toolkit)
    .skillRepository(skillRepo)
    .enableMetaTool(true)   // 让模型也能主动切换 tool group
    .build();

运行时行为 ：当 Agent 调用 load_skill_through_path 加载 data-analysis 时，analysis-tools 组自动激活，其中的 tool 立即可用。

8. Skill 执行脚本：配合 Shell 工具

Skill 只提供指令，真正的执行依赖 Agent 已有的 tool。如果 skill 指令涉及脚本执行，Agent 需要拥有 shell 能力：

java 复制代码

Toolkit toolkit = new Toolkit();

// 1. 启用 Shell 工具
import io.agentscope.core.tool.builtin.ShellTools;
toolkit.registerTool(new ShellTools(ShellConfig.localApproved()));

// 2. 注册 skill
ReActAgent agent = ReActAgent.builder()
    .name("SkillAgent")
    .model(model)
    .toolkit(toolkit)
    .skillRepository(skillRepo)
    .build();

// Agent 就能按 skill 指令执行 scripts/run.py 等脚本

9. 完整示例

java 复制代码

// 1. 准备 skill 目录
// skills/weather-analyzer/SKILL.md:
// ---
// name: weather-analyzer
// description: Analyze weather data and provide recommendations
// ---
// # Weather Analyzer Skill
// ## Instructions
// 1. Call get_weather for the specified city
// 2. Analyze the temperature, humidity, wind conditions
// 3. Provide clothing and activity recommendations

// 2. 注册 skill + 构建 Agent
ReActAgent agent = ReActAgent.builder()
    .name("WeatherSkillAgent")
    .model(DashScopeChatModel.builder()
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        .modelName("qwen-plus").build())
    .toolkit(toolkit)  // toolkit 中已注册了 get_weather 工具
    .skillRepository(new FileSystemSkillRepository(
        Paths.get("./skills")))
    .sysPrompt("你是一个天气助手，可以用 skill 来增强你的能力。")
    .build();

// 3. 调用
Msg reply = agent.call(List.of(
    Msg.builder().role(USER)
        .content(List.of(TextBlock.builder()
            .text("分析北京今天的天气并给出穿衣建议").build()))
        .build()
)).block();

10. Skill vs Tool 对比

维度	Skill	Tool
本质	Markdown 指令集	可执行代码
注册方式	`skillRepository(...)`	`toolkit.registerTool(...)`
调用方式	Agent 读取后按指令执行	Agent 直接调用
需要写代码	否（只写 Markdown）	是（Java 代码）
版本管理	Git / 文件系统 / Nacos / DB	随代码发布
适用场景	领域知识、工作流指引、指令模板	API 调用、数据操作、外部交互