技能Skill详解一句话概括技能系统就是给 Agent 装插件——你把写好的能力包放到指定位置Agent 就能在需要的时候自动加载并使用。你能学到什么什么是 Skill它和 Tool 有什么区别Skill 的两种安装来源技能市场和本地工作区四种 Repository 后端Git、Nacos、MySQL、Classpath各自的适用场景四层优先级机制同名 Skill 谁覆盖谁Builder API 的关键方法和使用时机写好 Skill 描述的最佳实践核心概念Skill技能— 手机上的 App想象你买了一部新手机。手机刚开机时只能打电话和发短信——这是 Agent 的基本能力比如对话、推理。现在你去应用商店下载了一个翻译 App、一个计算器 App、一个天气预报 App——这些 App 就是Skill。每个 App 有自己的说明文档SKILL.md告诉手机什么场景下该启动它。你不需要手动打开手机会在你说话时自动判断哦用户在问天气我该启动天气 App。Skill 和 Tool 的区别在于Tool工具Skill技能类比螺丝刀、锤子这样的手动工具一个装有工具和说明书的工具箱内容一个单独的函数/方法一整个目录包含 SKILL.md说明文档、references参考资料、scripts脚本获得方式代码里直接注册从市场下载或放到工作区复杂度通常只做一件事可以组合多步操作、带参考资料技能市场Skill Repository— 应用商店你手机上的应用商店就是技能市场。在 HarnessAgent 里技能市场有多种商店可选Git 仓库像团队的私有 GitHub 仓库大家把技能放上去共享Nacos像一个在线配置中心技能可以实时更新推送MySQL像一个企业内部管理系统统一存储和分发技能Classpath像手机出厂预装的 App跟着程序一起打包本地工作区Workspace Skills— 本地安装的 App除了从商店下载你也可以直接把技能文件放到工作区目录里就像你把 APK 文件直接拷贝到手机上安装一样。不需要任何注册放好就生效。工作区又分两种共用技能workspace/skills/所有用户都能看到像公司公告栏上贴的规章制度用户专属技能workspace/userId/skills/只有特定用户能看到像你抽屉里私人的笔记本四层优先级 — 食堂打饭排队规则想象你在公司食堂打饭排了四个窗口。高优先级的窗口可以盖过低优先级窗口的菜品优先级来源生活类比1最低项目全局目录公司总部的统一菜单——所有分公司都有的基础菜品2技能市场分公司自己加的菜品——可能覆盖总部菜单中的同名菜品3工作区共用你所在部门的部门特色菜——覆盖分公司的同名菜品4最高用户隔离目录你个人定制的私房菜——最高优先级覆盖前面所有的同名菜品关键规则下层独有的技能会保留只在重名时才用高优先级的版本覆盖。就像总部菜单有 10 个菜分公司加了 5 个其中 2 个和总部重名最终菜单是总部独有的 8 个 分公司独有的 3 个 分公司覆盖的 2 个 13 个菜。关键代码解读1. 最简示例接入 Git 技能市场HarnessAgentagentHarnessAgent.builder().name(assistant)// 给 Agent 起个名字.model(model)// 指定使用的大模型.workspace(workspace)// 指定工作区存放本地技能等// 核心一行创建一个 Git 技能仓库指向你团队的 Git 地址.skillRepository(newGitSkillRepository(https://github.com/your-org/team-skills.git)).build();// 构建 Agent就这么简单。构建完成后Agent 在推理时能看到这个仓库里所有技能的名称和描述需要用哪个就调用load_skill_through_path加载详细内容。2. Git Skill Repository — 最常用的技能来源!-- 第一步在 pom.xml 里加 Maven 依赖 --dependencygroupIdio.agentscope/groupIdartifactIdagentscope-extensions-skill-git-repository/artifactIdversion${agentscope.version}/version/dependency// 第二步在 Builder 里注册 Git 仓库.skillRepository(newGitSkillRepository(https://github.com/your-org/team-skills.git))Git 仓库的工作机制Agent 每次需要读取技能时会做一次轻量远端检查不是每次都完整拉取只有远端 HEAD 发生变化时才会真正 pull 新内容如果仓库里有skills/子目录会优先读取它否则读取根目录如果你想自己控制同步节奏可以关闭自动同步// false 关闭自动同步GitSkillRepositoryreponewGitSkillRepository(https://github.com/your-org/team-skills.git,false);// 在合适的时机手动调用 sync() 同步repo.sync();生活类比Git 技能仓库就像一个共享网盘。你不用每次都重新下载整个网盘而是先检查有没有新文件——有变化才下载没变化就用本地缓存。3. Nacos Skill Repository — 实时推送的技能中心!-- Maven 依赖 --dependencygroupIdio.agentscope/groupIdartifactIdagentscope-extensions-nacos-skill/artifactIdversion${agentscope.version}/version/dependency// 创建 Nacos 技能仓库// aiService: Nacos 的连接配置// namespace: Nacos 中的命名空间用于隔离不同环境的技能NacosSkillRepositorymarketnewNacosSkillRepository(aiService,namespace);HarnessAgent.builder().skillRepository(market)// 注册到 Agent.build();// 注意NacosSkillRepository 实现了 AutoCloseable// 应用退出时需要关闭释放订阅连接// try-with-resources 或者手动 close() 都行适用场景需要在线下发技能、技能内容可能随时变更的场景。Nacos 是一个配置中心技能更新后可以实时推送给所有 Agent。生活类比Nacos 像一个在线文档协作平台比如飞书文档。你在文档里改了内容所有打开这个文档的人立刻就能看到最新版本不需要手动刷新。4. MySQL Skill Repository — 企业级统一管理MysqlSkillRepositoryregistryMysqlSkillRepository.builder(dataSource).databaseName(agentscope)// 数据库名称.skillsTableName(skills)// 存技能元信息的表名.resourcesTableName(skill_resources)// 存技能资源文件的表名.createIfNotExist(true)// 表不存在时自动建表.writeable(true)// true 允许从 Agent 侧写回技能.build();// 如果只读分发传 falseHarnessAgent.builder().skillRepository(registry).build();适用场景平台侧统一管理技能时使用。比如你做了一个 AI 平台管理员在后台页面上传和管理技能所有 Agent 实例都从这个 MySQL 里读取。writeable(true)Agent 可以往数据库里写回新的技能适合用户自定义技能的场景writeable(false)只读模式Agent 只能读取不能写入适合集中分发的场景生活类比MySQL 技能仓库像一个公司内部的知识库系统比如 Confluence。管理员在上面统一管理文档普通员工只能看writeable(false)有权限的员工也可以编辑writeable(true)。5. Classpath Skill Repository — 打包随程序走首先在项目里放好技能文件src/main/resources/skills/ └── code-reviewer/ └── SKILL.md然后在 Builder 里注册// skills 是 classpath 下的目录前缀.skillRepository(newClasspathSkillRepository(skills))适用场景技能跟着 JAR 包一起发布。适合标准化、不会频繁变更的技能。生活类比Classpath 技能就像手机出厂时预装的 App——不用下载开机就有。但它也不容易更新要更新就得换手机重新打包 JAR。6. 接入多个技能市场// 方式一链式调用一个一个加HarnessAgent.builder().skillRepository(communityMarket)// 先加社区市场.skillRepository(internalRegistry)// 再加内部注册中心.skillRepository(teamGitRepo)// 最后加团队 Git 仓库.build();// 方式二一次性传入一组.skillRepositories(List.of(communityMarket,internalRegistry,teamGitRepo))重要细节skillRepositories(list)会清掉之前用skillRepository(...)添加的所有市场然后用传入的列表替换。所以不要混用两种方式。7. 工作区中的技能目录所有人共用优先级 3workspace/skills/ └── code-reviewer/ ├── SKILL.md # 技能说明文档 ├── references/ │ └── style-guide.md # 参考资料 └── scripts/ └── run-checks.sh # 配套脚本放在workspace/skills/下的技能所有用户都能看到和使用。单个用户专属优先级 4最高workspace/ ├── skills/code-reviewer/SKILL.md ← 共用版所有人可见 └── alice/ └── skills/ └── code-reviewer/ └── SKILL.md ← Alice 的覆盖版仅 Alice 可见Alice 调用时拿到她自己目录下的覆盖版Bob 调用时拿到共用版看不到 Alice 的那份Alice 如果在自己目录下放了一个新技能notes-taker只有她能用Bob 看不到前提条件用户隔离依赖RuntimeContext.userId调用方必须把userId传入RuntimeContext。8. 四层优先级完整示例假设有以下技能分布来源技能列表项目全局目录优先级 1code-reviewer、data-analyzerGit 市场优先级 2code-reviewer、translator工作区共用优先级 3code-reviewer、chart-makerAlice 用户目录优先级 4code-reviewer、notes-takerAlice 最终看到的技能列表技能名实际使用版本来源code-reviewerAlice 的覆盖版优先级 4最高notes-takerAlice 专属优先级 4只有 Alice 有chart-maker共用版优先级 3translator市场版优先级 2data-analyzer全局版优先级 1只有全局有总共 5 个技能不重复计算同名覆盖。整体流程图┌──────────────────────────────────────────────────────────────┐ │ HarnessAgent 构建 │ │ │ │ Builder 配置 │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ skillRepository() │ │ skillRepository() │ ... 可以多个 │ │ │ (Git/Nacos/ │ │ (MySQL/ │ │ │ │ MySQL/Classpath)│ │ Classpath) │ │ │ └────────┬─────────┘ └────────┬─────────┘ │ │ │ │ │ │ └──────────┬───────────┘ │ │ ▼ │ │ ┌─────────────────────┐ │ │ │ 合并为市场技能列表 │ 优先级 1-2 │ │ └──────────┬──────────┘ │ │ │ │ │ ┌───────────────────┼────────────────────┐ │ │ │ Workspace │ │ │ │ │ ┌──────────────┐ │ ┌──────────────┐ │ │ │ │ │ skills/ │ │ │ alice/skills/│ │ │ │ │ │ (共用技能) │ │ │ (用户专属) │ │ │ │ │ └──────┬───────┘ │ └──────┬───────┘ │ │ │ │ │优先级 3 │ │优先级 4 │ │ │ └─────────┼─────────┴─────────┼──────────┘ │ │ │ │ │ │ └────────┬──────────┘ │ │ ▼ │ │ ┌──────────────────────┐ │ │ │ 四层优先级合并 │ │ │ │ 4 3 2 1 │ │ │ │ 重名时高优先级覆盖 │ │ │ └──────────┬───────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Agent 可用技能列表 │ │ │ │ │ │ │ │ 每个 skill 只暴露 name description │ │ │ │ Agent 判断相关后才调用 load_skill_through_path │ │ │ │ 加载完整 SKILL.md references scripts │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────┘学习要点1. 技能 目录 SKILL.md技能就是一个文件夹里面至少要有SKILL.md。可以额外带references/参考资料和scripts/脚本。Agent 先看 name 和 description觉得相关才加载完整内容。2. 两种安装来源互不冲突技能市场通过skillRepository()注册适合集中管理的通用技能本地工作区放到workspace/skills/目录下适合项目特有的定制技能两种来源同时生效不需要二选一。3. 四层优先级是核心机制项目全局1 技能市场2 工作区共用3 用户隔离4低优先级独有的技能会保留只有同名时高优先级才会覆盖低优先级这是实现通用 定制的关键设计4. 四种 Repository 各有适用场景Repository适用场景特点Git团队共享技能版本控制轻量同步检查Nacos在线实时推送订阅变更需要关闭释放连接MySQL企业平台统一管理可读写适合后台管理界面Classpath随程序打包标准化不常变零配置5. description 写得好不好决定了 Agent 用不用这个技能Agent 最初只能看到每个技能的 name 和 description。如果 description 写得太笼统“这是一个数据分析工具”Agent 可能判断不准错过使用时机。应该写具体的触发场景“当用户要算统计、出报表、做趋势图时使用”。6. SKILL.md 控制在 2k tokens 左右详细内容放references/目录下脚本放scripts/目录下。Agent 需要时会自己读取这些附加文件。这样做的好处是避免一次性加载太多内容浪费 Token 和推理时间。7. 通用技能放市场项目特有写工作区代码评审、表格分析这类跨项目通用的技能放到 Git 市场集中维护。公司内部 RPC 规范、项目命名约定这类跟着项目走的技能写到workspace/skills/里跟着代码走版本控制。8. disableDynamicSkills() 的使用时机默认情况下Agent 每次推理前都会重新合并技能列表支持热更新。如果你的场景是单次任务跑完就退出或者接的市场后端比较慢可以调用disableDynamicSkills()在 build 时合并一次运行期不再变化。平时不需要动这个开关。