AgentScope Java新手村 Skills 技能系统详解

第十八章 Skills 技能系统：SKILL.md 文件协议与5层仓库，按需加载节省Token

先说一个判断——在AgentScope 1.x时代，“技能”这个概念其实有点模糊不清，业务方经常跑来问：“Skill和Tool到底有什么区别？”这回2.0版本算是给出了一个清晰干脆的定义，彻底把这件事理顺了。

18.1 什么是Skill？

想象一下，Skill可以理解为“操作手册+资料包”的组合体。主Agent会先读取SKILL.md文件里的description字段，判断这个技能是否适用于当前任务。如果决定要用，才会把SKILL.md的完整内容和相关附件加载到上下文中。这就像一个精明的项目经理，先看摘要决定要不要翻完整本手册。

18.2 第一个Skill：会议纪要

来看一个具体的例子，这个Skill专门用来整理会议纪要。首先在workspace下创建skills/meeting-minutes/目录，里面放两个文件：SKILL.md和template.md。 SKILL.md的内容是这样组织的： ``` --- name: meeting-minutes description: | 把对话内容整理成结构化会议纪要。当用户说"总结这段对话" / "写成会议纪要" / "提取action item" 时使用。 allowed-tools: [read_file] --- # Meeting Minutes Skill 你需要按下面的步骤把对话整理成会议纪要： 1. 提取每个 speaker 的关键发言 2. 提炼出 action item（谁 / 做什么 / 截止日期） 3. 用 `template.md` 的格式输出 4. 模板文件通过 `read_file` 读取 ``` 而template.md则定义了输出格式： ``` # 会议纪要 **时间**: **参与方**: ## 关键结论 - ... ## Action Items | 负责 | 事项 | 截止 | |------|------|------| | ... | ... | ... | ## 待讨论 - ... ``` 关键点在于，当你用HarnessAgent.builder().workspace(...)启动时，框架会自动扫描workspace/skills//SKILL.md，并将其注册到WorkspaceSkillRepository中。完全不用手动注册，省心省力。

18.3 5层SkillRepository组合

2.0版本把Skill仓库做成了接口，支持五种实现自由组合，按需选用： | 后端 | 适用 | 依赖 | |------|------|------| | WorkspaceSkillRepository | 本地workspace | 无（agentscope-harness自带） | | ClasspathSkillRepository | 内置/三方库里的skill | 无（agentscope-harness自带） | | GitSkillRepository | 团队Git仓库 | agentscope-extensions-skill-git-repository | | NacosSkillRepository | Nacos配置中心 | agentscope-extensions-nacos-skill | | MysqlSkillRepository | MySQL知识库 | agentscope-extensions-skill-mysql-repository | | PostgresSkillRepository | PostgreSQL知识库 | agentscope-extensions-skill-postgresql-repository | 如果需要使用非本地仓库，按需引入对应的Ma ven依赖即可： ```xml io.agentscope agentscope-extensions-skill-git-repository 2.0.0-RC2 io.agentscope agentscope-extensions-skill-mysql-repository 2.0.0-RC2 io.agentscope agentscope-extensions-skill-postgresql-repository 2.0.0-RC2 io.agentscope agentscope-extensions-nacos-skill 2.0.0-RC2 ``` WorkspaceSkillRepository和ClasspathSkillRepository已经内置于agentscope-harness中，完全不需要额外引入。 在配置时，多个仓库可以组合使用，声明顺序决定了优先级： ```ja va HarnessAgent agent = HarnessAgent.builder() .... .skillRepository( // 声明顺序 = 优先级：先本地 → 再 git → 再 nacos → 再 mysql → 再 postgres // 同名 skill 以先声明为准，后面的被忽略 new WorkspaceSkillRepository(filesystem, "skills", contextSupplier), // 本地 SKILL.md（最高优先级） new GitSkillRepository("https://github.com/your-org/team-skills.git"), // 团队公共 skill new NacosSkillRepository(nacosClient, "agentscope-skills"), // Nacos 配置中心 new MysqlSkillRepository(dataSource, "skill"), // MySQL skill 表 new PostgresSkillRepository(dataSource, "skill") // Postgres skill 表 ) .build(); ``` 这4层仓库按声明顺序查重：先workspace，再git，再nacos，再mysql。相同id的skill，以先声明的为准，后面的被忽略。

18.4 Skill加载的两个阶段

主Agent使用Skill的方式是按需加载，分为两个阶段。

18.4.1 路由阶段：只读description

主Agent启动时，所有skill的description会被拼接到system prompt里。LLM看到用户说“总结会议”时，知道有meeting-minutes这个skill可用，但此时还没读取完整内容。这就好比先看一眼目录，确定这本书有没有自己需要的章节。

18.4.2 加载阶段：按需读SKILL.md全文

LLM决定使用meeting-minutes后，会调用内置的read_skill工具，读取完整的SKILL.md以及附件路径，然后才开始干活。只有到这一步，才会把完整内容加载到上下文。这种按需加载机制，能有效节省token消耗。

18.5 在subagent上挂Skill

subagent和主Agent一样，也能挂载Skill： ```ja va SubagentDeclaration translator = SubagentDeclaration.builder() .name("translator") .description("中英互译") // 主 agent 通过 description 决定是否用这个 subagent .inlineAgentsBody("...") // 省略号替换为 subagent 的完整系统提示词 .skillRepository( new ClasspathSkillRepository("i18n"), // 来自 classpath:i18n/**/SKILL.md new GitSkillRepository("workspace-skills") // 团队 skill 仓库 ) .build(); ``` 主Agent通过subagent的description决定是否使用它，然后subagent再在自己的技能仓库中查找相应技能。

18.6 内置Skill：来自classpath

如果你的Skill不需要运行时更改，可以打包成jar包。在src/main/resources/skills/下创建目录： ``` src/main/resources/skills/payment-check/ ├── SKILL.md └── checklist.md ``` 然后通过ClasspathSkillRepository加载： ```ja va new ClasspathSkillRepository("skills") // "skills" 对应 classpath:skills/**/SKILL.md // 适合把标准操作手册打成 jar，下游项目引依赖即用 ``` 启动时会自动扫描classpath:skills/**/SKILL.md。这种方式非常适合把标准操作手册做成共享库，下游项目引入依赖即可使用。

18.7 Skill与Tool的区别

| 维度 | Tool | Skill | |------|------|-------| | 形态 | Ja va 方法 | Markdown 文件 | | 何时进入 prompt | 启动时全部注册 | 按 description 路由 + 按需加载 | | 业务方改动 | 改 Ja va + 重新编译 | 改 .md 文件即可 | | 适合 | 原子操作 | 流程、模板、领域知识 | 一个典型的组合方式是这样的： - read_file / grep_files —— Tool（原子操作） - meeting-minutes —— Skill（流程） 主Agent在meeting-minutes的allowed-tools里声明它需要read_file，这样LLM就知道“用这个skill时只能调用read_file这个工具”。

18.8 完整可运行示例

来看一个完整的项目结构： ``` workspace/ ├── MEMORY.md └── skills/ ├── meeting-minutes/ │ ├── SKILL.md │ └── template.md └── invoice-parser/ ├── SKILL.md └── rules.md ``` 每个SKILL.md的description就是主Agent看到的入口。以invoice-parser为例： ```yaml --- name: invoice-parser description: | 解析发片内容。当用户提供发片文本 / 提到"发片号 / 金额 / 税号"时使用。 allowed-tools: [read_file, parse_invoice] --- # Invoice Parser 1. 用 `parse_invoice` 工具从文本提取结构化字段 2. 用 `read_file` 读 `rules.md` 校验字段格式 3. 返回结构化结果 ``` rules.md定义了校验规则： ``` - 发片号：8 位数字 - 金额：保留 2 位小数 - 税号：18 位字母数字 ``` 主Agent的代码非常简单： ```ja va HarnessAgent agent = HarnessAgent.builder() .name("assistant") .sysPrompt("你是助理，会用 skill 解决具体问题。") .model(model()) .workspace(Path.of("./workspace")) // 设置了 .workspace()，框架自动扫描 workspace/skills/ 加载 SKILL.md // 无需手动注册 WorkspaceSkillRepository .build(); ``` 运行host.call("帮我把这段对话整理成会议纪要")时，LLM会先通过description路由到meeting-minutes，然后加载SKILL.md的完整内容，按照模板输出结果。

18.9 最小迁移清单（1.x SkillsKit → 2.0 SkillRepository）

| 1.x 用法 | 2.0 等价 | |----------|----------| | SkillsKit.register(skill) | SkillRepository + workspace/skills//SKILL.md | | agent.skills(kit) | HarnessAgent.builder().skillRepository(...) | | 业务方实现 Skill 接口 | 写 SKILL.md | | 技能库动态加载 | 多种 SkillRepository 后端 | | 跨项目复用 | ClasspathSkillRepository 打 jar / GitSkillRepository / PostgresSkillRepository |

18.10 本章小结

2.0版本用SKILL.md协议加SkillRepository抽象，彻底替代了1.x的SkillsKit。这里有几个核心要点值得记住： 第一，5种仓库后端——Workspace、Classpath、Git、Nacos、MySQL、PostgreSQL，按声明顺序查重，灵活组合。 第二，路由靠description，加载靠on-demand，这种机制能有效节省token成本。 第三，Skill与Tool互补——Tool是原子操作，Skill是流程编排。两者各司其职，共同构建起一个清晰、可扩展的技能系统。