## 1. Skill 的概念

前面几章我们给 agent 接了 Tool 和 MCP，agent 已经能做事了。但光能做事还不够，同样一句"帮我播报天气"，有的模型回答干巴巴一行，有的却格式工整，还带上建议和小贴士。差距在于 agent 知不知道该怎么做。

这类"做法"，比如播报格式、公司制度、代码规范、操作手册，不适合写成 Tool（没有执行逻辑），也不适合直接塞进 system prompt（太多会撑爆上下文）。Skill 就是为此设计的，把领域知识打包成一个一个的技能包，平时只暴露名字和简介，模型判断任务匹配时才加载全文。

### 1.1 AgentScope 中 Skill 的三个构件

- `AgentSkill` 一条技能，包含元数据（name、description）、技能文档（Markdown 指令）、可选的附属资源（参考文件、脚本）
- `AgentSkillRepository` 技能仓库，负责从某处批量加载技能。内置两种实现：`FileSystemSkillRepository`（本地目录）和 `ClasspathSkillRepository`（classpath 资源，可打进 jar 发布）
- `SkillBox` 装配层，启动时从仓库加载技能，把技能清单注入 system prompt，并注册一个 `load_skill_through_path` 工具，模型靠它按需激活技能

### 1.2 Skill 和 Tool、RAG 怎么选

三者都能给 agent 注入信息，定位不同：

| 手段  | 注入什么                 | 什么时候进上下文         | 典型场景                     |
| :---- | :----------------------- | :----------------------- | :--------------------------- |
| Tool  | 能力（执行逻辑）         | schema 常驻，调用时执行  | 查天气、下单、调 API         |
| Skill | 知识（做法、规范、流程） | 清单常驻，激活时加载全文 | 播报格式、公司制度、代码规范 |
| RAG   | 海量资料（检索式）       | 每次检索相关片段         | 产品手册、知识库问答         |

需要执行就用 Tool，需要教做法且条目不多就用 Skill，需要查资料且量大就用 RAG。三者不互斥，实际项目里经常一起上。

### 1.3 运行机制

Skill 最值得理解的是加载时机：

```
启动时：repository 扫描所有 SKILL.md
    → 只把「名字 + 描述」注入 system prompt 的 <available_skills> 清单
        → 模型收到任务，判断和某个技能相关
            → 模型调用 load_skill_through_path(skillId=..., path="SKILL.md")
                → 技能被激活，完整文档返回给模型
                    → 模型按照技能里的指令回答
```

技能文档平时不占上下文，用到才加载，官方管这叫渐进式披露。对比 MCP 那种所有工具 schema 全量注入的方式，技能多的时候 Skill 对上下文友好得多。

## 2. SKILL.md 怎么写

Skill 的载体就是一个特殊的 Markdown 文件：`SKILL.md`。目录结构：

```
skills
└── weather-report          ← 技能目录，一个技能一个目录
    └── SKILL.md            ← 技能定义文件
```

`SKILL.md` 分两部分：YAML frontmatter（元数据）和正文（技能文档）。以"天气播报规范"为例，这就是本章 demo 用的技能：

```markdown
---
name: weather-report
description: 当需要向用户播报天气时使用此技能。按照"笑小枫天气台"的固定格式播报天气，包含天气图标、温度区间、穿衣和出行建议。
---

# 笑小枫天气台播报规范

收到天气信息后，严格按照下面的格式播报。

## 播报格式

🌈 **笑小枫天气台**

📍 城市：{城市}
☀️ 天气：{天气现象}
🌡️ 温度：{最低温度} ~ {最高温度} 摄氏度

## 播报要求

1. 温度必须写成区间形式，单位为摄氏度
2. 根据天气现象给出一条穿衣建议（如晴天：适合穿薄外套）
3. 根据温度区间给出一条出行建议（如 18-28 度：早晚温差大，注意增减衣物）
4. 结尾附一句轻松的天气小贴士
5. 全文使用中文，语气轻松活泼
```

name 就是技能名，目录名和 name 保持一致，用英文小写加连字符（如 `weather-report`），和 Claude Code 等生态的技能格式兼容，也避免编码问题。

description 是整个技能最重要的字段。模型全靠它决定当前任务要不要加载这个技能，平时常驻 system prompt 的就是它。写法原则和 Tool 的 description 一样，写清楚什么时候用，别只写这是什么：

- ❌ `description: 天气播报`，模型不知道啥时候该用
- ✅ `description: 当需要向用户播报天气时使用此技能，按照固定格式播报…`，模型一看任务里有"播报天气"就能对上号

正文就是普通的 Markdown 指令，写给模型看的操作手册。格式模板、注意事项、示例都可以放，模型会照着执行。

## 3. 从文件系统加载技能

### 3.1 准备技能目录

在 demo 项目根目录建 `skills/weather-report/SKILL.md`，内容就是第 2 节那段。项目结构：

```
maple-agent-demo
├── src/main/java/com/maple/agent/demo/ReActAgent_06.java
└── skills
    └── weather-report
        └── SKILL.md
```

### 3.2 接入 agent

`ReActAgent.builder()` 直接提供了 `skillRepository` 方法，把目录指给它就完成了接入：

```java
public static void main(String[] args) {

    // 为了方便提及代码，不暴露隐私信息，密钥放到application-pro.yml中
    ConfigurableApplicationContext ctx = SpringApplication.run(MapleAgentApplication.class, args);
    OpenAiModelConfig props = ctx.getBean(OpenAiModelConfig.class);

    OpenAIChatModel model = OpenAIChatModel.builder()
            .baseUrl(props.getBaseUrl())
            .apiKey(props.getApiKey())
            .modelName(props.getModelName())
            .stream(true)
            .build();

    ReActAgent agent = ReActAgent.builder()
            .name("笑小枫的技能助手")
            .model(model)
            .sysPrompt("你是一个通用助手。")
            .toolkit(new Toolkit())
            .skillRepository(new FileSystemSkillRepository(Paths.get("skills")))
            .build();

    agent.streamEvents(new UserMessage("user", "帮我播报一下天气：上海今天晴，18-28摄氏度"))
            .doOnNext(event -> {
                if (event instanceof TextBlockDeltaEvent delta) {
                    System.out.print(delta.getDelta());
                } else if (event instanceof ToolCallStartEvent tc) {
                    System.out.println("\n[tool] " + tc.getToolCallName());
                } else if (event instanceof ToolResultEndEvent end) {
                    System.out.println("[tool result state=" + end.getState() + "]");
                }
            })
            .blockLast();
}
```

代码量少得可疑。我们没写播报逻辑，没注册任何 Tool，也没在 sysPrompt 里写播报格式，只给了一个目录路径。

运行一下：

![image-20260928085711863](https://developer.qcloudimg.com/http-save/yehe-8160077/ce022ced8d33b82f730a910d30c3c318.png)

从事件流里能看到模型调用了 `load_skill_through_path`，把技能文档加载进来后才组织回答：

![image-20260928090222248](https://developer.qcloudimg.com/http-save/yehe-8160077/234e7b57d1374f84f0c3e50c3239d4bd.png)

"笑小枫天气台"的播报格式、穿衣建议、小贴士全都出来了，这些内容不在代码里，也不在 prompt 里，就在那个 `SKILL.md` 里。以后要改播报风格，改 Markdown 就行，一行 Java 代码都不用动。

### 3.3 技能没生效？

最常见的原因是 description 写得太含糊，模型没意识到任务和技能相关。把事件流打出来，看模型有没有调 `load_skill_through_path`。没调，就去改 description；调了但效果不对，就去改正文指令。

## 4. 从 classpath 加载技能

`FileSystemSkillRepository` 适合本地开发和演示，但部署时技能目录得跟着应用走。技能是随应用发布的固定能力时，用 `ClasspathSkillRepository` 把它们打进 jar。

把技能目录放到 `src/main/resources/skills/` 下，然后：

```java
ReActAgent agent = ReActAgent.builder()
        // ...
        .skillRepository(new ClasspathSkillRepository("skills"))
        .build();
```

两者对 agent 来说没有区别，只是技能来源不同。实践中可以同时挂多个仓库（`skillRepositories` 方法接收列表），固定能力打进 jar，用户自定义技能放文件系统。

## 5. 进阶用法

### 5.1 代码方式定义技能

技能不一定来自 Markdown 文件，也可以用 `AgentSkill.builder()` 在代码里直接构造，配合 `SkillBox` 注册：

```java
Toolkit toolkit = new Toolkit();
SkillBox skillBox = new SkillBox(toolkit);
skillBox.registerSkill(AgentSkill.builder()
        .name("meeting-notes")
        .description("整理会议记录时使用，按照固定模板输出会议纪要")
        .skillContent("""
                # 会议纪要模板

                ## 会议信息
                - 时间：
                - 参会人：

                ## 结论事项
                1.

                ## 待办任务
                - [ ] 事项（负责人 / 截止时间）
                """)
        .build());

ReActAgent agent = ReActAgent.builder()
        .name("笑小枫的会议助手")
        .model(model)
        .toolkit(toolkit)
        .skillBox(skillBox)
        .build();
```

技能内容来自数据库、配置中心或代码生成、不想落盘成文件时用这种方式。`skillContent` 就是技能正文，等价于 `SKILL.md` 去掉 frontmatter 的部分。

### 5.2 SkillFilter 控制哪些技能可见

技能一多，不是所有技能都应该对所有人可见。`skillFilter` 可以做一层过滤：

```java
// 只暴露指定技能
.skillFilter(SkillFilter.only("weather-report", "meeting-notes"))

// 排除指定技能
.skillFilter(SkillFilter.except("internal-admin"))

// 默认全暴露
.skillFilter(SkillFilter.all())
```

典型的玩法是结合第 03 章的多用户会话，按用户身份过滤技能，普通用户看不到管理类技能。

### 5.3 技能和工具联动

Skill 教做法，Tool 供能力，两者可以绑定。Toolkit 的 `createSkillToolGroup` 能创建一个随技能激活的工具组，技能被激活时组里的工具自动对模型可用，技能停用后工具随之隐藏。比如"数据分析"技能激活时才放开执行 SQL 的工具，避免模型平时乱用。这块和上一章的 Tool Group 机制同源，用到时再展开。

## 本章小结

Skill 可以说是智能体的核心，但是分开写，发现又没有什么好写的，更多的使用方式，我这边会放到实战中进行演示吧。

本系列源码[https://gitee.com/hack-feng/maple-agent-demo](https://gitee.com/hack-feng/maple-agent-demo)

![AgentScope第6篇-Skill技能包一览图_笑小枫_1080x1920](https://developer.qcloudimg.com/http-save/yehe-8160077/efe499a9b85a9fa39e6e634d8307fb5a.png)

前面几章我们给 agent 接了 Tool 和 MCP，agent 已经能做事了。但光能做事还不够，同样一句"帮我播报天气"，有的模型回答干巴巴一行，有的却格式工整，还带上建议和小贴士。差距在于 agent 知不知道该怎么做。

AgentScope 学习系列 - 06：Skill 技能，让智能体随用随取的领域知识包

本文介绍AgentScope中Skill的概念与应用，旨在解决Agent“知如何做”而非仅“能做事”的问题。Skill将领域知识（如播报格式、规范）以SKILL.md形式封装，通过FileSystemSkillRepository或ClasspathSkillRepository加载，仅在调用时按需注入上下文，实现渐进式披露。

人工智能

开发工具

架构设计

Skill机制为Agent注入领域知识，通过渐进式披露按需加载技能文档，不占用上下文。支持文件系统与classpath两种加载方式，可配合Tool与RAG协同使用，提升回答规范性与上下文效率。

文件系统

数据分析

代码解释

智能体

数据库

Markdown

Agent

Java

2026上云采购 | AI焕新·智启新局

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

AgentScope 学习系列 - 06：Skill 技能，让智能体随用随取的领域知识包-腾讯云开发者社区-腾讯云

AgentScope 学习系列 - 06：Skill 技能，让智能体随用随取的领域知识包

AgentScope 学习系列 - 06：Skill 技能，让智能体随用随取的领域知识包

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐