一、为什么 Java 开发者要关注 Skills？

大模型时代，智能体（Agent）正在重塑软件开发的范式。但很多 Java 工程师在实际落地过程中面临以下挑战：

• 新框架要求 JDK 17+，老项目迁移成本高

• 工具调用逻辑复杂，学习曲线陡峭

• 缺乏生产级方案，Demo 好看但难落地

Agents-Flex 给出的答案是：用 JDK 8 + Skills 机制，让智能体开发回归简单。

而今天我们要深入探讨的 Skills，正是继 MCP（Model Context Protocol）之后，Agent 领域又一个爆发式增长的行业标准实践。

二、什么是 Skills？

2.1 Skills 的定义

如果把大模型想象成一个"超级实习生"，那 Skills 就是给它配备的"外接工具箱"。

传统的 AI 交互模式中，AI 的能力取决于：

1. 模型训练时学习到的知识（静态能力）

2. 用户在对话中临时提供的提示词（动态引导）

这种方式的问题在于：每次执行新任务，都需要重新描述操作流程，效率低、Token 消耗高、维护成本大。

Skills 的核心价值：将重复性、专业化的业务流程进行模块化封装，形成可复用的"能力插件"。当需要某项能力时，模型可以像调用工具一样直接使用，无需重复输入冗长的提示词。

2.2 Skills 的文件结构

Skills 采用基于文件系统的设计规范，每个 Skill 都是一个独立的目录，结构清晰：

skills/
├── convert_to_pdf/
│   ├── SKILL.md          # 核心指令：定义技能的目标、步骤、注意事项
│   ├── reference/        # 参考文档：更详细的操作指南（可选）
│   ├── scripts/          # 执行脚本：Python/Node.js/Java 等（可选）
│   └── assets/           # 静态资源：图片、模板等（可选）
├── send_email/
│   └── SKILL.md
└── ...

2.3 SKILL.md 编写规范

以 convert_to_pdf 技能为例：

---
name: convert_to_pdf
description: 将文本内容转换为 PDF 文件，支持自定义文件名和基础样式配置
---

## 目标
将用户提供的文本内容，生成标准格式的 PDF 文件，并返回文件路径。

## 使用步骤
1. 确认用户提供的文本内容（content）和期望的文件名（filename）
2. 调用底层 PDF 生成工具执行转换操作
3. 返回生成的文件路径，并告知用户下载或预览方式

## 注意事项
- 不要擅自修改用户原文内容
- 不要替用户决定文件名（除非用户未明确指定）
- 如果内容过长，需提前告知用户可能影响生成效率
- 生成失败时，应返回清晰的错误信息而非静默失败

关键字段说明：

• name：技能的唯一标识，建议使用英文小写+下划线命名

• description：决定技能何时被触发，描述越具体，越容易被模型准确识别和调用

2.4 核心机制：渐进式披露（Progressive Disclosure）

Skills 最巧妙的设计在于"按需加载"机制，有效解决大模型上下文窗口有限、Token 成本高昂的问题。

加载过程分为三个层级：

第一层：元数据（Metadata）

• 加载内容：仅 name + description

• 资源消耗：每个技能约几百 Token

• 作用：让模型感知"可用能力清单"，但不知具体实现细节

第二层：指令（Instructions）

• 触发条件：用户请求与某技能的 description 匹配

• 加载内容：读取对应目录下的 SKILL.md 全文

• 作用：模型理解该技能的操作流程、输入输出规范、边界约束

第三层：运行时资源（Runtime）

• 触发条件：执行具体操作步骤时

• 加载内容：按需读取 reference 文档、scripts 脚本、assets 资源

• 关键优势：脚本代码本身不进入 Prompt，仅执行结果反馈给模型

示例：用户请求"帮我把 Hello World 转成 PDF"

1. 模型扫描 Skills 元数据，发现 convert_to_pdf 匹配

2. 加载该技能的 SKILL.md，理解操作流程

3. 调用 scripts/convert.py 执行转换，仅将执行结果（文件路径）返回模型

4. 模型生成最终回复："PDF 已生成：/tmp/output.pdf"

全程仅加载必要信息，Token 消耗相比全量注入方式降低 90% 以上。

三、Skills 与 MCP 的关系辨析

很多开发者容易混淆 Skills 和 MCP，以下从多个维度进行对比：

3.1 两者并非替代关系，而是互补协作

MCP 的核心价值在于制定标准接口，统一 AI 连接外部世界的方式。如果你是一个通用平台（如高德地图、Notion），希望发布工具供各类 Agent 调用，MCP 仍是首选方案。

Skills 的核心价值在于封装业务逻辑，将重复性工作流程标准化、模块化。如果你有一套固定的代码 Review 流程、文档生成规范、数据分析 SOP，Skills 是更轻量的实现方式。

3.2 未来技术格局展望

Agent 核心能力层（基础操作：bash/read/edit/write）
│
├── 连接层：少量通用 MCP Server
│    └── 职责：连接远程数据库、云 API、第三方 SaaS
│
└── 能力层：大量 Skills 插件
     └── 职责：封装本地工作流、业务规则、领域知识

Skills 负责"教 AI 怎么做事"，MCP 负责"帮 AI 连接世界"，两者协同工作，构建完整的能力体系。

四、代码实战：JDK8 + Agents-Flex 加载 Skills 智能体

以下代码展示如何使用 JDK 8 + Agents-Flex 构建一个支持 Skills 调用的智能体应用：

public class Main {

    public static void main(String[] args) throws InterruptedException {

        // 1. 配置大模型连接参数
        OpenAIChatModel chatModel = OpenAIChatConfig.builder()
            .provider("GiteeAI")
            .endpoint("https://ai.gitee.com")
            .requestPath("/v1/chat/completions")
            .apiKey(System.getenv("GITEE_APIKEY"))  // 建议通过环境变量管理密钥
            .model("Qwen3.5-35B-A3B")
            .thinkingEnabled(false)
            .buildModel();

        // 2. 初始化对话上下文，设置系统提示词引导模型使用 Skills
        MemoryPrompt prompt = new MemoryPrompt();
        prompt.setSystemMessage("Always use the available skills to assist the user in their requests.");

        // 3. 构建用户请求
        UserMessage userMessage = new UserMessage("帮我把 \"Hello world\" 这个内容成一个 PDF 文件。");

        // 4. 注册 Skills 工具 + 通用工具集
        Tool skillsTool = SkillsTool.builder()
            .addSkillsDirectory("/path/to/your/skills")  // 指定 Skills 目录，支持热加载
            .build();
        userMessage.addTool(skillsTool);
        userMessage.addTools(CommonTools.getAllCommonsTools()); // 内置常用工具：文件/网络/时间等

        prompt.addMessage(userMessage);

        // 5. 定义流式响应监听器，实现工具调用闭环
        StreamResponseListener listener = new StreamResponseListener() {
            @Override
            public void onMessage(StreamContext context, AiMessageResponse response) {
                // 提取模型返回内容（优先 content，其次 reasoningContent）
                String content = StringUtil.hasText(response.getMessage().getContent()) 
                    ? response.getMessage().getContent() 
                    : response.getMessage().getReasoningContent();
                System.out.println(">>>>> " + content);

                // 判断是否触发工具调用
                if (response.getMessage().isFinalDelta() && response.getMessage().getToolCalls() != null) {
                    // 将模型的工具调用请求加入对话历史
                    prompt.addMessage(response.getMessage());
                    
                    // 遍历并执行所有工具调用
                    for (ToolCall toolCall : response.getMessage().getToolCalls()) {
                        System.out.println(">>>>> " + toolCall.getName() + ": " + toolCall.getArguments());
                        // 执行工具并获取结果消息
                        List<ToolMessage> toolMessages = response.executeToolCallsAndGetToolMessages();
                        // 将工具执行结果反馈给模型，形成闭环
                        prompt.addMessages(toolMessages);
                    }
                    // 递归发起下一轮对话，直到任务完成
                    chatModel.chatStream(prompt, this);
                } elseif (response.getMessage().isFinalDelta() && !response.getMessage().hasToolCalls()){
                    // 无后续工具调用，任务结束
                    System.out.println(">>>>>>> 结束 <<<<<<<<<");
                }
            }
        };

        // 6. 启动流式对话
        chatModel.chatStream(prompt, listener);
        
        // 注意：生产环境建议使用 CompletableFuture 管理异步，避免 Thread.sleep 阻塞
        Thread.sleep(200000L);
    }
}

五、方案优势分析

5.1 真正的 JDK 8 兼容

• 代码全程使用 Java 8 语法，无 var、record、Switch Expression 等新特性

• 老项目无需升级 JDK 或构建工具，直接引入依赖即可使用

• 与 SpringBoot 2.x/3.x、Quarkus 等主流框架无缝集成

• 支持 JDK8 ~ JDK25

5.2 Skills 热加载，开发效率提升

Tool skillsTool = SkillsTool.builder()
    .addSkillsDirectory("/path/to/your/skills")
    .build();

• 修改 .skill 配置文件后，下次对话自动生效，无需重启服务

• 支持多目录配置，便于团队分工协作

• Skills 目录可纳入 Git 版本管理，配合 CI/CD 实现自动化同步

5.3 渐进式加载，显著降低 Token 成本

Agents-Flex 的 Skills 实现严格遵循"元数据→指令→资源"的加载策略：

1. 应用启动时，仅解析每个 Skill 的 name + description（约几百 Token）

2. 用户请求匹配时，才加载对应 SKILL.md 的详细指令

3. 执行阶段按需读取 scripts/reference，且脚本源码不进入 Prompt

对比测试：传统方式将 50 个技能的完整说明书注入 Prompt，单次对话消耗约 5 万 Token；Skills 机制下，首次对话仅需 2 千 Token，成本降低 96%。

5.4 工具调用全自动闭环，聚焦业务逻辑

用户请求 
  ↓ 
模型分析 → 匹配 Skills 元数据 → 加载对应指令
  ↓ 
框架自动解析参数 → 执行绑定脚本（Java/Python/Node.js）
  ↓ 
执行结果返回模型 → 模型生成最终回复
  ↓ 
用户收到结构化结果

开发者只需关注业务逻辑实现，框架自动处理工具发现、参数解析、结果反馈等"胶水代码"。

六、典型应用场景

所有 Skills 均采用"纯文本配置 + 脚本绑定"模式，非技术人员经过简单培训即可参与维护，降低团队协作门槛。

七、总结与展望

"优秀的框架不是要求开发者学习新语法，而是帮助开发者用已有知识解决新问题。"

Agents-Flex 始终坚持三个核心原则：

1. 真开源：采用 Apache License 2.0 协议，无商业绑定，社区共建

2. 易集成：JDK 8+ 友好，最小化依赖，与现有 Java 技术栈无缝融合

3. 生产就绪：流式响应、渐进式加载、工具管理、异常处理等生产级能力全覆盖

如果你属于以下角色：

• 希望用 Java 构建 AI 应用的后端工程师

• 正在评估智能体技术选型的系统架构师

• 推动团队向 AI Native 转型的技术负责人

欢迎体验 Agents-Flex，一起用熟悉的语言，构建可靠的智能系统。

作者简介：Michael Yang（杨福海），Agents-Flex 以及 AIFlowy (Gitee 2025 年度最佳 "人工智能" 开源项目)等 AI 项目发起人，小码科技创始人。长期致力于推动 Java AI 生态标准化，坚持 Apache Way 开源理念。

生产环境建议

1. 使用 CompletableFuture 替代 Thread.sleep 管理异步流程，避免阻塞主线程

2. 结合 Sentinel 实现工具调用的熔断降级，保障系统高可用

3. Skills 目录建议纳入 Git 管理，配合 CI/CD 实现团队协同与版本控制

4. 针对 Web 应用，应该使用 Docker 等来执行 Skills

完整源码： https://gitee.com/agents-flex/agents-flex/tree/v2.x/demos/skills-demo