Skills 梳理skills你可以把Skills理解成给大模型准备的一套“可复用的技能说明书”或者“操作手册包”。它不是 Spring Boot 里的技能而是 LangChain4j 让 LLM 更有针对性地完成任务的一种机制。1. Skills 是什么文档里说Skills is a mechanism for equipping an LLM with reusable, self-contained behavioral instructions.翻译成通俗的话就是Skills 是一种给大模型外挂“技能包”的机制。比如你希望大模型在不同场景下有不同的专业能力场景对应 Skill帮用户修改 Word 文档docxSkill帮用户分析数据data-analysisSkill帮用户写 SQLsqlSkill帮用户审查 Java 代码java-code-reviewSkill帮用户生成 Spring Boot 接口springboot-apiSkill每个 Skill 都是一套独立的说明它告诉大模型当遇到某类任务时你应该怎么做、遵循什么规则、参考哪些资料。2. Skills 解决什么问题如果不用 Skills我们通常会把大量系统提示词、规则、业务规范一次性塞进 Prompt 里。问题是Prompt 太长浪费 Token。用户问一个很简单的问题也要带上一大堆无关规则。不同任务的规则混在一起模型容易混乱。维护困难提示词越来越臃肿。Skills 的思路是先只告诉模型有哪些技能每个技能是干什么的。当模型判断某个技能有用时再按需加载这个技能的详细说明。所以它的核心作用是让大模型按需加载专业能力而不是一开始就塞满所有上下文。3. Skills 的组成一个 Skill 通常包含这些东西Skill ├── name技能名称 ├── description技能描述 ├── content技能的详细说明也就是给 LLM 的指令 └── resources可选资源例如参考文档、模板、案例等3.1 name技能名称例如name:docx作用告诉模型这个技能叫什么。可以理解为一个唯一标识。比如docx>3.2 description技能描述例如description:Edit and review Word documents using tracked changes意思是使用修订模式编辑和审阅 Word 文档。作用让模型快速判断这个技能适不适合当前用户的问题。比如用户说帮我审阅一下这个 Word 合同并保留修改痕迹。模型看到docx这个 Skill 的描述就知道这个技能应该被用上。3.3 content技能内容也就是SKILL.md中 YAML 头部下面的正文部分。例如When the user asks you to edit a Word document: 1. Always use tracked changes so edits can be reviewed. ...翻译一下当用户要求你编辑 Word 文档时 1. 一定要使用修订模式这样修改内容可以被审阅。 ...作用这部分是真正给 LLM 的详细操作说明。它可以写遇到什么情况要怎么做输出格式应该是什么哪些事情不能做优先级规则业务规范示例处理流程你可以把它理解成这个技能的详细 Prompt。3.4 resources技能资源文档里说Any file in the skill directory, other than SKILL.md itself and files under a scripts/ subdirectory, is automatically loaded as a SkillResource.也就是说在技能目录下除了SKILL.md scripts/ 目录下的文件其他文件都会被自动当作资源加载。比如skills/ └── docx/ ├── SKILL.md └── references/ └── tracked-changes.md这里的references/tracked-changes.md就是一个资源文件。作用是给模型提供额外参考资料。比如tracked-changes.md里面可以写# Word 修订模式规范 1. 所有正文修改必须保留修改痕迹。 2. 不要直接覆盖原文。 3. 对关键条款修改需要添加批注。这样模型在需要的时候可以读取这个资源。4. Skills 是实验性 API文档特别提示The Skills API is experimental. APIs and behavior may still change in future releases.意思是Skills API 目前还是实验性的。对 Spring Boot 开发者来说这意味着API 以后可能会改。类名、方法名可能会变。行为可能会调整。生产环境使用要谨慎。升级 LangChain4j 版本时要特别注意 Release Notes。如果你现在是学习和调研非常适合。如果马上用于核心生产业务建议做好封装避免未来升级时改动面太大。5. Skills 遵循 Agent Skills 规范文档说Skills are designed according to the Agent Skills specification.意思是LangChain4j 的 Skills 设计参考了 Agent Skills 规范。简单理解它不是随便设计的一个 Prompt 文件格式而是参考了面向 Agent 的技能规范。这对以后构建 Agent 很有帮助。比如以后你可能会做文档处理 Agent数据分析 Agent代码审查 Agent客服 Agent运维 Agent每个 Agent 都可以挂载不同的 Skills。6. 如何创建 Skill文档介绍了两种方式从文件系统加载从 Classpath 加载这两种方式对 Spring Boot 开发者非常重要。7. 方式一从文件系统加载 Skills文档示例目录结构skills/ ├── docx/ │ ├── SKILL.md │ └── references/ │ └── tracked-changes.md └──>skills/ 技能根目录 ├── docx/ 一个 docx 技能 │ ├── SKILL.md docx 技能说明文件 │ └── references/ docx 技能的参考资料 │ └── tracked-changes.md └──>SKILL.md7.1 SKILL.md 的格式示例--- name: docx description: Edit and review Word documents using tracked changes --- When the user asks you to edit a Word document: 1. Always use tracked changes so edits can be reviewed. ...它分成两部分。第一部分是 YAML Front Matter---name:docxdescription:Edit and review Word documents using tracked changes---这里声明技能元信息name技能名称 description技能描述第二部分是正文When the user asks you to edit a Word document: 1. Always use tracked changes so edits can be reviewed. ...这里是技能指令内容。7.2 为什么要用 YAML Front Matter因为 LangChain4j 需要通过它解析出技能的基础信息。类似很多 Markdown 文档里的元数据---title:xxxauthor:xxxdate:xxx---在 Skills 里面它至少需要name:xxxdescription:xxx7.3 文件系统加载适合什么场景从文件系统加载适合这些情况Skills 不想打进 Jar 包。技能内容希望可以动态修改。运维人员或业务人员可以直接修改 Skill 文件。多个应用共享同一套 Skills 目录。想实现类似配置中心的效果。例如/opt/app/skills/ ├── springboot-api/ ├── sql-review/ └── customer-service/Spring Boot 应用启动时从这个目录加载 Skills。8. 引入依赖文档给的 Maven 依赖是dependencygroupIddev.langchain4j/groupIdartifactIdlangchain4j-skills/artifactIdversion1.17.1-beta27/version/dependency作用引入 LangChain4j 的 Skills 模块。注意这里的版本是1.17.1-beta27带有beta再次说明这个功能还比较新。在你的项目里版本最好和你当前使用的 LangChain4j 主版本保持一致。9. 使用 FileSystemSkillLoader 加载 Skills文档代码ListFileSystemSkillskillsFileSystemSkillLoader.loadSkills(Path.of(skills/));意思是从文件系统的skills/目录加载所有 Skill。这里会加载skills/docx/ skills/data-analysis/也就是skills/下面的直接子目录。9.1 加载全部 SkillsListFileSystemSkillskillsFileSystemSkillLoader.loadSkills(Path.of(skills/));作用一次性加载某个目录下所有技能。适合应用启动时初始化。比如 Spring Boot 里你可以这样理解BeanpublicListFileSystemSkillskills(){returnFileSystemSkillLoader.loadSkills(Path.of(skills/));}当然具体怎么注入到你的 AI Service还要根据你使用的 LangChain4j 版本和 API 来定。9.2 加载单个 Skill文档代码FileSystemSkillskillFileSystemSkillLoader.loadSkill(Path.of(skills/docx));作用只加载一个技能。适合你只想针对某个场景加载特定 Skill。比如FileSystemSkilldocxSkillFileSystemSkillLoader.loadSkill(Path.of(skills/docx));10. 方式二从 Classpath 加载 Skills文档介绍了另一个加载器ClassPathSkillLoader它和FileSystemSkillLoader类似但是加载位置不同。10.1 什么是 Classpath 加载在 Java / Spring Boot 项目里src/main/resources下的文件会被打包进 Jar。例如src/main/resources/ └── skills/ ├── docx/ │ ├── SKILL.md │ └── references/ │ └── tracked-changes.md └──>ClassPathSkillLoader.loadSkills(skills);来加载。10.2 Classpath 加载适合什么场景适合这些情况Skills 是应用的一部分。不希望外部用户随意修改。希望随着 Jar 一起发布。适合稳定的系统规则。适合版本化管理。比如你做一个 Spring Boot AI 应用里面内置几个固定技能src/main/resources/skills/ ├── java-code-review/ ├── springboot-api/ ├── sql-optimization/ └── customer-service/然后跟着代码一起提交 Git。这样技能文件也能版本管理。11. 使用 ClassPathSkillLoader 加载 Skills11.1 加载全部 Skills文档代码ListFileSystemSkillskillsClassPathSkillLoader.loadSkills(skills);作用从 classpath 下的skills目录加载所有技能。对应目录src/main/resources/skills/11.2 加载单个 Skill文档代码FileSystemSkillskillClassPathSkillLoader.loadSkill(skills/docx);作用只加载skills/docx这个技能。对应目录src/main/resources/skills/docx/11.3 默认使用线程上下文 ClassLoader文档说By default, ClassPathSkillLoader uses the thread’s context class loader.意思是默认情况下ClassPathSkillLoader使用当前线程的 Context ClassLoader。对普通 Spring Boot 应用来说通常你不用关心这个。只有在这些特殊场景下才可能需要自定义 ClassLoader插件化系统多 ClassLoader 环境应用服务器环境自定义模块隔离测试框架中动态加载资源12. FileSystemSkillLoader 和 ClassPathSkillLoader 的区别对比项FileSystemSkillLoaderClassPathSkillLoader加载位置操作系统文件目录Java Classpath典型目录/opt/app/skills或项目根目录下skills/src/main/resources/skills是否打进 Jar不一定会打进 Jar是否方便动态修改方便不方便需要重新打包是否适合配置化适合一般是否适合内置能力一般非常适合Spring Boot 推荐场景外部可维护技能应用内置技能13. 用 Spring Boot 开发者的视角理解 Skills你可以把 Skills 类比成以下东西13.1 类似配置文件就像application.yml里面写系统配置。而SKILL.md里面写大模型行为配置。13.2 类似策略模式比如你在 Java 里可能会写interfaceHandler{booleansupport(Requestrequest);Responsehandle(Requestrequest);}不同任务有不同 Handler。Skills 类似于给大模型的“策略处理说明”。例如用户问 Word 处理 - docx Skill 用户问数据分析 ->13.3 类似插件机制每个 Skill 是一个独立目录skills/docx/ skills/data-analysis/ skills/sql-review/你可以新增、删除、修改某个技能不影响其他技能。14. 一个适合 Spring Boot 项目的 Skills 示例比如你要做一个 AI 编程助手可以这样组织src/main/resources/ └── skills/ ├── springboot-api/ │ ├── SKILL.md │ └── references/ │ └── rest-api-style.md ├── mybatis-sql/ │ ├── SKILL.md │ └── references/ │ └── sql-style.md └── code-review/ ├── SKILL.md └── references/ └── java-review-checklist.md14.1 springboot-api/SKILL.md 示例--- name: springboot-api description: Help design and generate Spring Boot REST APIs --- When the user asks you to design or generate a Spring Boot REST API: 1. Use layered architecture: - Controller - Service - ServiceImpl - Mapper or Repository - DTO - VO 2. Use standard Spring annotations: - RestController - RequestMapping - GetMapping - PostMapping - RequestBody - PathVariable 3. Return unified response objects. 4. Add basic parameter validation when needed. 5. Explain the code in simple Chinese.这个 Skill 的作用是当用户要求生成 Spring Boot 接口时让模型按照你指定的代码风格和架构生成代码。14.2 mybatis-sql/SKILL.md 示例--- name: mybatis-sql description: Help write and optimize MyBatis SQL and mapper code --- When the user asks about MyBatis or SQL: 1. Prefer clear and maintainable SQL. 2. Avoid SELECT *. 3. Explain possible indexes. 4. For dynamic conditions, use MyBatis dynamic SQL tags properly: - if - choose - where - foreach 5. Consider SQL injection risks.作用让模型在回答 MyBatis 和 SQL 问题时遵守你的团队规范。14.3 code-review/SKILL.md 示例--- name: code-review description: Review Java and Spring Boot code for bugs, maintainability and security --- When the user asks you to review Java or Spring Boot code: 1. Check null pointer risks. 2. Check transaction boundary issues. 3. Check exception handling. 4. Check security risks. 5. Check SQL performance. 6. Give suggestions in this format: - Problem - Risk - Suggestion - Example作用让模型成为一个“代码审查专家”。15. Skills 的执行过程可以这样理解假设你配置了两个 Skilldocx>帮我分析一下这个 CSV 文件里的销售趋势。大概过程是LLM 先看到有哪些 Skills。它发现data-analysis的描述和用户问题相关。它决定使用data-analysisSkill。LangChain4j 加载这个 Skill 的详细内容。如果需要它还会读取 Skill 目录下的资源文件。模型基于 Skill 指令回答用户。这样就不需要一开始把docx、data-analysis、sql、code-review等所有详细规则都塞进上下文。16. Skills 和普通 Prompt 的区别对比项普通 PromptSkills组织方式通常是一大段文本每个技能独立目录是否可复用可以但容易混乱天然可复用是否按需加载一般不是是是否适合多场景场景多了会变复杂更适合是否方便维护大 Prompt 难维护每个 Skill 单独维护是否支持资源文件需要自己处理Skill 目录下资源可自动加载17. Skills 和 Tools 的区别你学习 LangChain4j 的时候可能还会看到 Tools也就是 Function Calling。这两个容易混淆。简单区分概念主要作用类比Skills告诉模型“怎么做”操作手册、行为规范Tools让模型“调用外部能力”Java 方法、接口、函数举个例子用户说帮我查一下订单 1001 的物流状态并按照客服话术回复。这里可能同时用到Tool用于真正查询订单getOrderShippingStatus(1001)Skill用于规定回复风格你是客服助手回复要礼貌、简洁、先安抚用户再说明状态。所以Tool 偏执行动作。Skill 偏行为指导。18. Skills 和 RAG 的区别RAG 是检索增强生成主要是从知识库中找相关资料再给模型回答。Skills 是给模型加载某种行为规则和操作说明。区别概念解决问题RAG让模型知道“某些知识”Skills让模型知道“应该怎么做”比如公司报销制度适合放 RAG。回答报销问题时必须先问发票类型、金额、日期适合放 Skill。19. 什么时候应该用 Skills适合用 Skills 的情况你有多个任务场景。每个任务场景有不同规则。规则比较长不适合每次都放进 Prompt。希望提示词模块化管理。希望 AI 按需加载能力。希望团队共同维护 Prompt。希望把 AI 能力做成插件包。比如客服回复规则 合同审查规则 代码审查规则 SQL 优化规则 文档改写规则 数据分析规则这些都适合做成 Skills。20. 什么时候不一定需要 Skills如果你的应用很简单比如用户问什么模型直接回答。或者你的系统提示词只有几句话你是一个 Java 开发助手请用中文回答。那就没必要马上上 Skills。Skills 更适合复杂、多场景、可复用的 AI 应用。21. 对 Spring Boot 项目的建议如果你是 Spring Boot 开发者我建议你这样选学习阶段使用 Classpath 方式src/main/resources/skills/好处是简单跟项目一起管理。生产阶段如果技能规则经常变使用 FileSystem 方式/opt/your-app/skills/好处是不需要重新打包应用。推荐目录结构src/main/resources/ └── skills/ ├── springboot-api/ │ ├── SKILL.md │ └── references/ │ └── coding-style.md ├── sql-review/ │ ├── SKILL.md │ └── references/ │ └── mysql-index-guide.md └── customer-service/ ├── SKILL.md └── references/ └── reply-template.md22. 你可以这样理解整个 Skills 页面总结一下这篇文档的核心内容内容点是什么作用SkillsLLM 的技能包机制给模型按需加载专业能力Experimental实验性 API提醒你未来可能变化Agent Skills specificationAgent 技能规范让 Skills 更适合 Agent 场景SKILL.md技能定义文件声明技能名称、描述和详细指令YAML front matterMarkdown 顶部元数据定义name和descriptioncontent技能正文告诉模型具体怎么做resources技能资源文件给模型提供额外参考资料FileSystemSkillLoader文件系统加载器从外部目录加载技能ClassPathSkillLoaderClasspath 加载器从resources或 Jar 内加载技能loadSkills加载多个技能批量初始化loadSkill加载单个技能针对某个技能单独加载23. 一句话总结LangChain4j Skills 就是把大模型的复杂提示词拆成一个个可复用、可维护、可按需加载的“技能包”。对于 Spring Boot 开发者来说你可以把它理解成用 Markdown 文件管理 AI 的专业能力用 Loader 在应用启动时加载让大模型根据用户问题自动选择合适的技能说明。