【AgentScope 2.0】08-技能系统（Skill）详解

版本基准:本文档基于 AgentScope 2.0 GA(v2.0.0)编写。具体版本号以 Release Notes 为准。一句话概括技能系统就是给 Agent 发工作手册——你把写好的 Markdown 指令包放到指定位置Agent 就能在需要的时候自动加载、按手册干活2.0 还加了自学习闭环让 Agent 自己写手册、经审批后变成正式技能。你能学到什么Skill 的本质Markdown 格式的指令集SKILL.md YAML frontmatter四层优先级机制全局目录 市场 工作区共用 用户隔离同名时谁覆盖谁常用技能市场Skill Repository后端FileSystem / Classpath / Workspace内置 Git / Nacos / MySQL / PostgreSQL扩展共 7 种自学习三阶段工具注册 → 晋升门控 → 后台清理市场技能的物化机制.skills-cache/和 SHA-256 去重files-root在不同文件系统模式下的解析方式技能使用追踪.usage.json和编程 API写好技能描述的最佳实践前置知识详见 README.md 前置知识部分。本篇额外需要工作区目录结构知道workspace/skills/和userId/skills/在哪参考 02-workspace.mdMiddleware 机制了解技能注入发生在每轮推理前参考 01-overview.md核心概念Skill 的本质 —— 就像工作手册生活类比想象你在工厂流水线上工作。厂长发给你一本工作手册封面写着名称和用途YAML frontmatter里面是具体的操作步骤Markdown 正文。手册旁边还附了几页参考资料和一把专用工具——这些就是references/和scripts/。你不需要把整本手册背下来只要看到封面就知道哦这个场景该翻哪本手册用到的时候再打开细看。技术解释一个 Skill 就是一个目录里面至少包含一份SKILL.md文件。SKILL.md由两部分组成顶部的 YAML frontmatter声明name和description以及正文给 Agent 看的操作指令。目录里还可以附带references/参考资料和scripts/可执行脚本。code-reviewer/ ├── SKILL.md # 必需YAML 头部 Markdown 指令 ├── references/ # 可选长篇参考资料 │ └── style-guide.md └── scripts/ # 可选Agent 可以调用的脚本 └── run-checks.shSKILL.md长这样--- name: code-reviewer description: 当用户需要代码评审、风格反馈或 PR 审核时使用。 --- # Code Reviewer 步骤 1. 读 references/style-guide.md 获取项目规范 2. 跑 scripts/run-checks.sh 目标路径把结果汇总给用户Agent 推理时先看到name和description判断相关才加载完整内容。所以description 写得好不好直接决定 Agent 用不用这个技能。四层优先级 —— 就像公司文档级别生活类比想象你是一家大公司的员工手边有四类文档全球规范公司总部发的所有分公司都必须遵守的基础制度部门文档你所在部门加的可能覆盖全球规范里的同名条目团队共享你小组自己定的覆盖部门文档里的同名条目个人笔记你自己写的最高优先级覆盖前面所有同名条目关键规则低级别独有的文档会保留只在重名时才被高级别覆盖。就像总部有 10 个制度部门加了 5 个其中 2 个和总部重名最终你看到的是总部独有的 8 个 部门独有的 3 个 部门覆盖的 2 个 13 个。技术解释四个技能来源都可能给出同名技能优先级从低到高优先级来源怎么配生活类比1最低项目全局目录projectGlobalSkillsDir(Path)公司总部发的全球规范2技能市场skillRepository(...)后注册的覆盖先注册的部门文档3工作区共用workspace/skills/团队共享文档4最高用户隔离userId/skills/个人笔记举例团队 Git 上有通用code-reviewer项目workspace/skills/code-reviewer/写了项目专属版本Agent 看到的就是项目版Alice 又在自己目录覆盖了一份那 Alice 调用时拿到她自己的版本其他用户还是项目版。技能市场Skill Repository —— 就像应用商店生活类比技能市场就像手机上的应用商店。你可以从不同的商店下载 App——有的商店是 Git 仓库像团队的私有代码仓库有的商店是 Nacos像在线文档平台实时推送更新有的商店是 MySQL像企业内部管理系统统一审批上架还有的商店是 Classpath像手机出厂预装的 App跟着系统一起走。技术解释技能市场通过skillRepository(...)注册常用后端如下Git / Nacos / MySQL / PostgreSQL / Classpath后端适用场景特点Git团队共享技能版本控制轻量同步检查Nacos在线实时推送订阅变更需要 close 释放连接MySQL企业平台统一管理可读写适合后台管理界面PostgreSQL企业平台统一管理可读写与 MySQL 后端对等Classpath随程序打包标准化不常变零配置可以接多个市场skillRepository(...)重复调用即可后注册的优先级更高。自学习三阶段 —— 就像员工提建议 → 经理审批 → HR 归档生活类比想象公司有一套员工建议机制提建议员工Agent在工作中发现了一个好做法写成一份草拟文档放到待审批文件夹。这就对应enableSkillManageTool()——让 Agent 能自己写技能草稿。经理审批草拟文档不能直接生效得经过经理审核。经理还可以控制这份建议先在小范围试用——这就对应enableSkillPromotionGate()——晋升门控 环境过滤 金丝雀灰度。HR 归档时间长了有些过期的建议需要清理归档。HR 定期翻一遍超过 30 天没引用的标为过时超过 90 天的收进档案柜。这就对应enableSkillCurator()——后台周期性整理。技术解释Harness 提供了一套让 Agent 自己起草 / 沉淀 / 整理 Skill的闭环各阶段独立可开阶段Builder 方法Agent 获得的能力1. 工具注册enableSkillManageTool()propose_skill写草稿skill_manage编辑已有技能2. 晋升门控enableSkillPromotionGate()审核闸门 环境过滤 金丝雀灰度3. 后台清理enableSkillCurator()定期标记过期、归档无用技能GA 技能中间件体系:上述能力背后是一组中间件(在agent.middleware.*包):HarnessSkillMiddleware—— 技能加载与注入核心。每轮推理前按需加载技能(load_skill_through_path),并负责marketplace 技能资源的预阶段(见 07-sandbox 工作区投影)SkillCuratorMiddleware—— 后台周期性清理,对应enableSkillCurator()SkillUsageMiddleware—— 统计技能使用情况,为 curator 的过期判定提供数据启用顺序也有讲究没人写新技能之前开 curator 没意义。先开第 1 步再加第 2 步让审核介入最后用第 3 步处理老的。晋升门控Promotion Gate —— 就像试用期转正生活类比新员工入职后有试用期。试用期结束要经过经理签字审核闸门才能转正。转正后也不是所有人立刻都能看到这个新员工的工作成果——可能先在测试环境试运行环境过滤或者先让 10% 的人看到金丝雀灰度确认没问题了再全面铺开。技术解释晋升门控由两部分组成——闸门Gate和可见性过滤Filter闸门草稿要变成正式技能必须经过它。内置三种直接拒绝默认、本地人工确认stdin、推消息后等可见性过滤决定 Agent 推理时能看到哪些自己创建的技能。可按部署环境、灰度比例、白名单组合.enableSkillPromotionGate(newLocalApprovalGate(LocalApprovalGate.defaultPrompter()),// 闸门谁批newCompositeFilter(List.of(// 过滤怎么暴露newEnvironmentFilter(prod,skillUsageStore),newCanaryFilter(0.10,skillUsageStore)// 10% 灰度))).environment(prod)物化机制Materialization —— 就像把电子文档打印出来生活类比市场里的技能最初只存在电子文档里内存中。但如果 Agent 要通过 shell 执行脚本就必须拿到真实的纸质文件磁盘上的实际文件。这个从电子变纸质的过程就是物化。而且打印很聪明——用 SHA-256 检查每个文件的内容指纹只重印有变化的页面不浪费纸张。技术解释市场技能的资源最初在内存中。要让 shell 能执行它们的脚本harness 在每轮推理前把市场技能物化到wsRoot/.skills-cache/source/name/目录文件级SHA-256 去重只重写变化过的文件已下架技能留下的孤儿目录会在同一轮顺手清掉Sandbox 模式下.skills-cache默认包含在 workspace projection roots 里跟workspace/skills/一起 hydrate 进沙箱工作区技能Layer 3 / 4不需要物化——它们本来就在磁盘上。关键代码解读1. 最简示例接入 Git 技能市场把团队的技能仓库接进来Agent 立刻就能用。HarnessAgentagentHarnessAgent.builder().name(assistant)// 给 Agent 起个名字.model(model)// 指定大模型.workspace(workspace)// 指定工作区// 核心一行创建 Git 技能仓库指向团队地址.skillRepository(newGitSkillRepository(https://github.com/your-org/team-skills.git)).build();// 构建 Agent构建完成后Agent 在推理时能看到仓库里所有技能的名称和描述需要用哪个就调load_skill_through_path加载详细内容。2. 常用市场后端的配置Git 后端——最常用的团队共享方式!-- pom.xml 中添加依赖 --dependencygroupIdio.agentscope/groupIdartifactIdagentscope-extensions-skill-git-repository/artifactIdversion${agentscope.version}/version/dependency// 自动同步模式每次读取时轻量检查远端HEAD 变了才 pull.skillRepository(newGitSkillRepository(https://github.com/your-org/team-skills.git))// 手动同步模式自己控制同步节奏GitSkillRepositoryreponewGitSkillRepository(https://github.com/your-org/team-skills.git,false);repo.sync();// 在合适的时机手动同步Nacos 后端——实时推送的技能中心// 创建 Nacos 技能仓库NacosSkillRepositorymarketnewNacosSkillRepository(aiService,namespace);HarnessAgent.builder().skillRepository(market)// 注册到 Agent.build();// 注意NacosSkillRepository 实现了 AutoCloseable// 应用退出时需要 close() 释放订阅连接MySQL 后端——企业平台统一管理MysqlSkillRepositoryregistryMysqlSkillRepository.builder(dataSource).databaseName(agentscope)// 数据库名.skillsTableName(skills)// 技能表名.createIfNotExist(true)// 表不存在时自动建表.writeable(true)// true 允许从 Agent 侧写回.build();// false 只读分发HarnessAgent.builder().skillRepository(registry).build();Classpath 后端——打包随程序走// 技能文件放在 src/main/resources/skills/ 下.skillRepository(newClasspathSkillRepository(skills))3. 自学习三阶段配置阶段 1让 Agent 能自己写技能HarnessAgent.builder()...// 启用技能管理工具Agent 获得 propose_skill skill_manage.enableSkillManageTool(SkillManageConfig.defaults()).build();// 如果想让草稿写完直接生效不推荐生产环境用.enableSkillManageTool(true)// autoPromote true启用后 Agent 获得两个工具propose_skill把新技能写成草稿到skills/_drafts/name/等审核skill_manage编辑已有技能创建 / 修改 / 添加附属文件 / 删除框架还会自动记录技能使用计数到skills/.usage.json为后续的清理和灰度提供数据。阶段 2加审核闸门 可见性过滤.enableSkillPromotionGate(// 闸门谁来审批这里用本地 stdin 确认newLocalApprovalGate(LocalApprovalGate.defaultPrompter()),// 过滤怎么暴露给 Agent组合多种过滤策略newCompositeFilter(List.of(newEnvironmentFilter(prod,skillUsageStore),// 只在 prod 环境可见newCanaryFilter(0.10,skillUsageStore)// 10% 金丝雀灰度))).environment(prod)// 当前部署环境标识阶段 3后台周期性整理.enableSkillCurator(SkillCuratorConfig.builder().intervalHours(7*24)// 每周跑一次.minIdleHours(2)// 距上次调用至少 2 小时才允许跑.staleAfterDays(30)// 30 天没用 → 标记为 stale.archiveAfterDays(90)// 90 天没用 → 归档到 .archive/.build())4. 编程 API手动触发技能操作业务层可以通过以下 API 手动操作// 查询审计日志某天以来所有技能操作记录ListSkillAuditLog.Entryentriesagent.queryAudit(LocalDate.now(),e-true);// 立刻跑一次整理绕过节流闸门agent.runCuratorOnce().subscribe(report-System.out.println(report));// 手动晋升一份草稿为正式技能agent.promoteSkill(notes-taker,alice).subscribe(result-System.out.println(result));5. Agent 读取技能的内部机制每轮推理时Agent 会在 system prompt 里看到一个available_skills块available_skillsskillnamecode-reviewer/namedescription当用户需要代码评审、风格反馈或 PR 审核时使用。/descriptionskill-idcode-reviewer_workspace-namespaced/skill-idfiles-root/workspace/skills/code-reviewer/files-root/skill/available_skillsAgent 觉得某个技能相关就调用load_skill_through_path(skillId, path)加载详情load_skill_through_path(skillId, SKILL.md)→ 返回 Markdown 正文load_skill_through_path(skillId, references/style-guide.md)→ 返回指定文件不同来源的底层解析方式不同但 Agent 感知不到这种差异调用起来都一样技能来源path 解析方式项目全局目录Layer 1注册时预载到内存市场Layer 2后端预载到内存工作区共用Layer 3注册时预载到内存用户隔离Layer 4SKILL.md 预载其他文件通过AbstractFilesystem按需读取6.files-root在不同模式下的解析当技能自带脚本时Agent 需要绝对路径才能通过 shell 执行。这个路径就是files-root它的值取决于文件系统模式文件系统模式工作区技能的files-root市场技能的files-rootSandbox/workspace/skills/name/workspace/.skills-cache/source/nameLocal-with-shellwsRoot/skills/namewsRoot/.skills-cache/source/nameLocal 不带 shell / Composite不渲染没注册 shell 工具不渲染所以 Agent 发出的 shell 命令永远是execute_shell_command(python3 files-root/scripts/foo.py)——不用猜路径。7. Builder 常用选项速查方法说明skillRepository(repo)追加一个市场可重复调用skillRepositories(list)一次性替换所有市场清掉之前的projectGlobalSkillsDir(path)启用项目全局目录目录不存在则跳过disableDynamicSkills()关掉每轮重新合并改成 build 时合并一次子 Agent 自动继承父的市场列表和项目全局目录不用重复配。整体流程图┌─────────────────────────────────────────────────────────────────────┐ │ HarnessAgent 构建 │ │ │ │ Builder 配置技能来源 │ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ │ │ projectGlobal- │ │ skillRepository() │ │ skillRepository() │ │ │ │ SkillsDir() │ │ (Git / Nacos / │ │ (MySQL / │ │ │ │ 优先级 1 │ │ Classpath) │ │ Classpath) │ │ │ └────────┬─────────┘ │ 优先级 2 │ │ 优先级 2 │ │ │ │ └────────┬─────────┘ └────────┬─────────┘ │ │ │ │ │ │ │ └──────────┬──────────┴──────────────────────┘ │ │ ▼ │ │ ┌─────────────────────┐ │ │ │ 市场技能合并Layer 1-2│ │ │ └──────────┬──────────┘ │ │ │ │ │ ┌───────────────────┼───────────────────────┐ │ │ │ Workspace │ │ │ │ │ ┌──────────────┐ │ ┌─────────────────┐ │ │ │ │ │ skills/ │ │ │ userId/skills/│ │ │ │ │ │ (共用 Layer 3)│ │ │ (隔离 Layer 4) │ │ │ │ │ └──────┬───────┘ │ └───────┬─────────┘ │ │ │ └─────────┼─────────┴──────────┼────────────┘ │ │ │ │ │ │ └─────────┬──────────┘ │ │ ▼ │ │ ┌──────────────────────────┐ │ │ │ 四层优先级合并 │ │ │ │ 4 3 2 1 │ │ │ │ 重名时高优先级覆盖 │ │ │ └────────────┬─────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ 市场技能物化Materialization │ │ │ │ │ │ │ │ 内存中的市场技能 ──SHA-256 去重──▶ .skills-cache/source/ │ │ │ │ 清理已下架技能的孤儿目录 │ │ │ └──────────────────────────┬───────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ available_skills 注入 system prompt │ │ │ │ │ │ │ │ 每个 skill 只暴露 name description files-root │ │ │ │ Agent 判断相关后调 load_skill_through_path 加载完整内容 │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ 自学习闭环可选三个阶段独立开启 │ │ │ │ │ │ │ │ ① enableSkillManageTool() │ │ │ │ Agent 获得 propose_skill / skill_manage 工具 │ │ │ │ 自动记录 .usage.json 使用追踪 │ │ │ │ │ │ │ │ │ ▼ │ │ │ │ ② enableSkillPromotionGate() │ │ │ │ 草稿 → 闸门审批 → 环境过滤 金丝雀灰度 → 正式技能 │ │ │ │ │ │ │ │ │ ▼ │ │ │ │ ③ enableSkillCurator() │ │ │ │ 后台定期扫描30 天 stale → 90 天归档到 .archive/ │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘模块关系与学习顺序工作区技能以SKILL.md和配套文件存在工作区中并按作用域合成文件系统负责从本机、远端存储或沙箱加载技能文件并完成物化缓存子 Agent子代理声明可以绑定技能Skill 增加“做事方法”SubAgent 增加“执行人手”记忆自学习流程从实际任务中提炼候选技能经门控后沉淀为可复用知识学习要点必须记住技能 目录 SKILL.md技能就是一个文件夹里面至少有SKILL.mdYAML 头部 Markdown 指令可以附带references/和scripts/。Agent 先看 name 和 description觉得相关才加载完整内容。四层优先级是核心机制项目全局1 技能市场2 工作区共用3 用户隔离4。低优先级独有的技能保留只在重名时高优先级覆盖。这是实现通用 定制的关键设计。自学习三阶段要按顺序开先开enableSkillManageTool()让 Agent 能写技能再加enableSkillPromotionGate()让审核介入最后用enableSkillCurator()处理过期的。顺序反了没有意义。市场技能需要物化才能执行脚本市场技能最初在内存中harness 通过.skills-cache/目录物化到磁盘用 SHA-256 去重避免重复写入。description 决定 Agent 用不用这个技能写数据分析工具远不如写当用户要算统计、出报表、做趋势图时使用有效。容易混淆skillRepository()vsskillRepositories()skillRepository(repo)追加一个市场可以链式调用多次skillRepositories(list)一次性替换所有市场会清掉之前用skillRepository()添加的两种方式不要混用草稿Draft vs 正式技能Promoted Skill草稿存在skills/_drafts/下Agent 不一定能看到正式技能经过晋升门控审批后才生效autoPromotetrue可以跳过审批直接生效不推荐生产用Layer 3 工作区共用 vs Layer 4 用户隔离workspace/skills/是所有人都能看到的共用技能userId/skills/是特定用户专属的覆盖/补充技能前提是调用时RuntimeContext.userId传了用户名实践建议通用能力放市场项目特有的写工作区代码评审、表格分析这类跨项目通用的技能放 Git 市场集中维护公司内部 RPC 规范、项目命名约定写到workspace/skills/里跟着代码走版本。SKILL.md 控制在 2k tokens 左右详细内容放references/脚本放scripts/。Agent 需要时会自己读取避免一次性加载太多内容浪费 Token。用户目录用来覆盖 补充不要当主存放关键能力请放在所有用户都能看到的层市场或工作区共用用户目录只做个性化定制。disableDynamicSkills()只在特定场景用单次任务跑完就退出、或者市场后端比较慢时可以关掉每轮重新合并。平时不要动这个开关。常见问题Q两个市场仓库的getSource()返回值一样怎么办A第二个会自动加后缀source_2、source_3…并打 warning log。路径和 skill-id 不会撞。所以你不用担心两个仓库的名字冲突。QAgent 怎么知道什么时候该用哪个技能A靠description。Agent 一开始只看到每个技能的 name 和 description觉得相关才会load_skill_through_path加载详情。所以 description 要写具体的触发场景不要写笼统的概括。Qpropose_skill写的草稿放在哪A放在skills/_drafts/name/目录下。经过晋升门控审批后才会移动到正式的技能目录变成生效技能。Q.skills-cache/可以手动清理吗Aharness 每轮推理前会自动清理孤儿目录已下架或从 builder 移除的技能留下的文件。一般情况下你不需要手动清理。