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

1.x 的 io.agentscope.core.skill.SkillsKit 在 2.0 中被整体替换。新版基于 SkillRepository + workspace/skills/<id>/SKILL.md 文件协议，并支持 5 层仓库组合（Workspace / Git / Nacos / MySQL / PostgreSQL / Classpath）。

本章你将学到：Skill 协议长什么样、4 层仓库如何组合、运行时如何"按主题加载"、以及如何把团队的最佳实践打包成可复用的 Skill。

18.1 什么是 Skill？

1.x 的"技能"概念被弱化——业务方经常困惑"Skill 和 Tool 有什么区别"。2.0 给 Skill 一个清晰定义：

Skill = 一份结构化的"领域知识包"，包含：

1. 元信息（SKILL.md）—— name、description、allowed-tools
2. 可选的代码 / 模板 / 文档附件 —— 与 SKILL.md 同目录的其他文件
3. 路由 —— 主 agent 看到 description 后决定是否加载

把 Skill 想成"操作手册 + 资料包"：主 agent 读 SKILL.md 的 description 决定要不要用，用的时候才把 SKILL.md 完整内容 + 附件读进上下文。

18.2 第一个 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：

# 会议纪要

**时间**: <date>
**参与方**: <participants>

## 关键结论
- ...

## Action Items
| 负责 | 事项 | 截止 |
|------|------|------|
| ... | ... | ... |

## 待讨论
- ...

HarnessAgent.builder().workspace(...) 启动时会自动扫描 workspace/skills/<id>/SKILL.md 注册到 WorkspaceSkillRepository。

18.3 5 层 SkillRepository 组合

2.0 把"Skill 仓库"做成接口，支持 5 个实现自由组合：

需要非本地仓库时，按需引入对应扩展：

<!-- Git 仓库 -->
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-skill-git-repository</artifactId>
    <version>2.0.0-RC2</version>
</dependency>

<!-- MySQL 仓库 -->
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-skill-mysql-repository</artifactId>
    <version>2.0.0-RC2</version>
</dependency>

<!-- PostgreSQL 仓库 -->
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-skill-postgresql-repository</artifactId>
    <version>2.0.0-RC2</version>
</dependency>

<!-- Nacos 仓库 -->
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-nacos-skill</artifactId>
    <version>2.0.0-RC2</version>
</dependency>

WorkspaceSkillRepository 和 ClasspathSkillRepository 在 agentscope-harness 里，无需额外依赖。

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();

注意：WorkspaceSkillRepository 的构造器需要 AbstractFilesystem 和 RuntimeContext 提供者。普通场景无需手动构造——设置了 .workspace() 后，HarnessAgent 自动扫描 workspace/skills/ 目录加载 Skill。只有当你想把 workspace 之外的其他路径也作为 skill 来源时才需要显式注册。

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 + 附件路径，再开始干活。

这种"按 description 路由 + 按需加载"是 2.0 比 1.x 节省 token 的关键——10 个 skill 不会一次塞满 10 份 SKILL.md。

18.5 在 subagent 上挂 Skill

subagent 跟主 agent 一样能挂 Skill：

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();

18.6 内置 Skill：来自 classpath

如果你的 skill 不需要运行时改，可以打成 jar：

src/main/resources/skills/payment-check/
├── SKILL.md
└── checklist.md

new ClasspathSkillRepository("skills")
// "skills" 对应 classpath:skills/**/SKILL.md
// 适合把标准操作手册打成 jar，下游项目引依赖即用

启动时自动扫描 classpath:skills/**/SKILL.md。

适合三方库：把"标准行业操作手册"打成 jar，下游项目引依赖就能用。

18.7 Skill 与 Tool 的区别

一个常见的组合：

• 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 路由（每个 skill 的 description 是主 agent 看到的入口）：

---
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 代码：

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）

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 是流程。