概述

Skills 是 AgentScope 的 filesystem skills 机制。Skill 适合承载"什么时候使用""如何执行"的长指令，也可以把某些 Java @Tool 只绑定到指定 skill 上，避免所有工具都全局暴露给 Agent。

名词约定

本章涉及的 load_skill_through_path、SkillBox 都是 AgentScope 内部 API，由 liteflow-react-agent-core 自动接入，业务侧不需要直接调用。你只需关心：在 liteflow.agent.skills.path 下放 SKILL.md，在组件里通过 skills() 选用即可。

开启 Skills

Skills 默认关闭。开启后，框架会从 liteflow.agent.skills.path 指向的目录扫描技能：

liteflow.agent.skills.enabled=true
liteflow.agent.skills.path=./skills
liteflow.agent.skills.strict=true

配置项	默认值	说明
liteflow.agent.skills.enabled	false	是否启用 skills 支持
liteflow.agent.skills.path	./skills	skills 根目录，每个子目录表示一个 skill
liteflow.agent.skills.strict	true	严格模式：目录缺失、skill 不存在等问题会快速失败

路径建议

skills.path 支持绝对路径和相对路径，与 workspace.root 同样基于 JVM user.dir 解析。生产环境建议使用绝对路径（如 /opt/liteflow/skills），避免不同启动方式定位到不同目录。

目录结构与 SKILL.md

skills/
├── demo/
│   └── SKILL.md
└── tool-skill/
    └── SKILL.md

最小 SKILL.md 示例：

---
name: demo
description: Demo skill for LiteFlow Re-Act agent
---

# Demo Skill

Use this skill when the request is about a simple demonstration.

name 是组件 skills() 过滤时使用的技能名。建议让目录名与 name 保持一致。

组件级技能过滤

限制 Agent 只能在指定技能内选择：

@Override
protected List<String> skills() {
    return List.of("demo", "tool-skill");
}

语义说明：

• 返回空列表：允许使用 skills.path 下的全部技能
• 返回非空列表：只把这些技能放入本 Agent 的 SkillBox
• 严格模式下，白名单中有不存在的技能会抛出异常

也可以在全局开启时对单个组件禁用 skills：

@Override
protected boolean enableSkills() {
    return false;
}

Skill 专属 Java 工具

如果某个 Java 工具只应随指定 skill 可用，可以在 SKILL.md frontmatter 中声明 tools：

---
name: tool-skill
description: Skill that binds a Java tool
tools: com.example.agent.tool.SkillEchoTool
---

tools 的值是工具类的全限定类名，支持以下几种 YAML 写法：

• 单个：tools: com.example.Tool1
• 逗号分隔多个：tools: com.example.Tool1, com.example.Tool2
• 行内数组：tools: [com.example.Tool1, com.example.Tool2]

也支持块列表（多行，每行一个）写法：

tools:
  - com.example.Tool1
  - com.example.Tool2

工具类要求：

• 必须在应用 classpath 上
• 推荐注册为框架容器（Spring / Solon）的 bean：框架会优先按类型从容器获取实例，从而让依赖注入生效；只有容器中没有该类型、容器尚未就绪或获取异常时，才降级为反射调用无参构造器（此时依赖注入不可用）。因此工具类要么是容器管理的 bean，要么至少提供一个公有无参构造器作为兜底
• 工具方法按 agentscope-java 的 @Tool / @ToolParam 方式声明

记录本轮使用的技能

usedSkills() 返回当前 invocation 中已经成功加载过的技能名列表：

@Override
protected void handleReply(Msg reply) {
    ctx().getSlot().setOutput(getNodeId(), Map.of(
            "reply", reply == null ? "" : reply.getTextContent(),
            "skillsUsed", usedSkills()
    ));
}

使用边界：

• 每次 process() 开始前会清空上一轮记录
• 只记录 load_skill_through_path 成功加载的技能
• 可在 process() 触发的调用链内读取（如 handleReply()）

代码执行边界

开启 Skills 等于开启代码执行

开启 skills 后，框架会在 conversation workspace 内启用 AgentScope 的代码执行能力（skillBox.codeExecution().enable()）。这条路径走的是 AgentScope 自身的执行通道，独立于 liteflow.agent.shell.*——即使把 liteflow.agent.shell.mode 设为 DISABLED，开启 skills 后代码执行路径依然存在，也不受 Shell 白名单 / 黑名单约束。生产环境开启前请评估这条路径的安全影响，并严格管控 skills.path 与其引用 Java 工具类的来源。