Skip to main content

如何添加一个自定义技能(SKILL)

本教程说明如何在 GIS Agent 中新增一个自定义技能,并让它在技能市场中可见、在对话中可被 Agent 调用。适用于本机开发环境,也适用于离线 / 内网部署的目标机。 阅读对象:需要给 GIS Agent 扩展新能力(新技能)的实施或开发人员。你不需要改任何构建脚本, 绝大多数情况下只是”放一个文件夹 + 跑一条同步命令”。

先理解:一个技能是什么

一个技能(SKILL)就是仓库 skillpacks/ 下的一个目录,目录里至少有一个 SKILL.md:
SKILL.md 顶部用 frontmatter 声明技能的 name 与 description:
  • name:技能唯一标识,也是技能市场卡片的标题。用小写字母、数字、连字符。
  • description:Agent 判断”什么时候该用这个技能”的依据,务必写清用途 + 触发场景。
  • 正文:写给 Agent 的操作指引,越具体越稳定。技能可以引用同目录下的脚本、模板等文件。

关键心智模型:两条独立链路

新增技能时最容易踩的坑,是把”市场里看得见”和”对话里用得上”当成同一件事。它们是两条独立 链路: 一句话结论:
只要文件进了卷,技能市场就能看到;要让 Agent 在对话里真正用上它,还需要登记 skills.paths。

步骤一:在开发机(仓库)里创建技能

1. 从模板工程开始(推荐)

官方在 gisagent/custom/skill/hello-gis/ 提供了一个最小但完整的 SKILL 模板工程,包含:
  • SKILL.md:frontmatter + 触发词 + 调用行为
  • scripts/hello.sh:辅助脚本(演示 SKILL 如何引用目录内文件)
  • README.md:说明与改造建议
你可以直接复制这个目录改造成自己的技能:
SKILL.md 顶部用 frontmatter 声明技能的 name 与 description:
  • name:技能唯一标识,也是技能市场卡片的标题。用小写字母、数字、连字符。
  • description:Agent 判断”什么时候该用这个技能”的依据,务必写清用途 + 触发场景。
  • 正文:写给 Agent 的操作指引,越具体越稳定。技能可以引用同目录下的脚本、模板等文件。
参考实现:skillpacks/mapgis-custom-skill/ 是另一个常驻参考(纯 SKILL.md 无脚本版本), skillpacks/hello-gis/ 是带辅助脚本的版本。两者都可用于验证扩展链路。

2. 登记到 skills.paths(仅”对话可调用”需要)

编辑 config/opencode/opencode.json,在 skills.paths 数组追加一行:
路径是容器内路径,固定以 /workspace/skills/<技能目录名> 开头,目录名要和第 1 步一致。 如果只需要技能市场显示、不需要对话调用,这一步可以省略。

3. 本机快速验证(可选,免重打包)

在输出里能看到你的技能 name 与 location,说明 agent 侧已发现它。 关于”读的是哪份配置”(重要,实测确认):opencode debug skill 与 opencode mcp list 读的是 运行容器里当前生效的 opencode 配置——容器内全局 ~/.config/opencode/opencode.json,并与 OPENCODE_CONFIG_CONTENT 合并;它不直接读仓库的 config/opencode/opencode.json。
  • 第 2 步改仓库文件是交付路径:要经”重新打包 → 重启 gisagent → 重建运行实例”才进聊天。
  • 想免重打包快速核对,把技能目录临时加进容器生效的 skills.paths,再验证:
    验证后可把这条临时路径从容器配置里删掉;正式生效仍以改仓库 config/opencode/opencode.json 并重打包为准。

步骤二:部署到目标机

有两种方式,按需选择。

方式 A:重新打包 offline bundle 再部署(推荐,交付用)

在开发机改完第 1、2 步后,直接重新打包。package.sh 会:
  • 把 skillpacks/ 整个目录原样拷进 bundle(不需要改 package.sh,新技能自动进包);
  • 把 opencode.json 的 skills.paths / mcp 同步进运行配置,供 Agent 读取。

方式 B:在已部署的目标机上就地添加(调试 / 增量交付)

适合目标机已经跑起来、只想快速加一个技能。技能市场显示(链路①)只需做完前三步。 在目标机的 bundle 目录下执行:
到这里,刷新一次技能市场页面就能看到新技能(链路①完成)。 若还要让 Agent 在对话里用上它(链路②),继续第 4 步登记 skills.paths。注意改对载体: 运行实例(含 Web UI 临时容器)读的是挂载 profile config/local/agent.local-*.json 里 OPENCODE_CONFIG_CONTENT 的 skills.paths,不是 bundle 的 config/opencode/opencode.json (后者是打包期源文件):
生效顺序固定为:改配置 → 定向重启 gisagent(+ agent-opencode)→ 新建会话。旧会话会缓存 技能快照,务必用新会话验证。

方式 C:热更包(L0+L1,带备份与健康闸门,推荐现场增量)

上面的方式 B 手工步骤,对应 docker-hot-update 框架的两层:L0 刷卷(免重启,等价 skillpacks-sync),L1 配置热更(profile 的 skills.paths + 定向 restart)。用框架脚本 可以把”改哪份载体、漏没漏重启”这类人为事故变成自动化:
执行器自带 preflight → 备份 → 定向 apply → 健康闸门(失败自动回滚),历史在 <栈目录>/.hotfix-backups/hotfix-history.log。撤销热加同样是”还原 profile / 卷内容后再打 一个还原包”。该链路 2026-09-23 已在本机栈用临时技能完成”应用 → Web UI 新会话验收 → 同链路清理”闭环(新会话实测 Loaded skill: hotfix-demo-skill,验收后已移除)。 新版 bundle 已内置 scripts/hot-update.sh(package.sh 自 2026-09-23 起同步拷贝); 旧 bundle 目录把该脚本单独拷进去也能用,或直接走方式 B 的手工步骤。
无论方式 B 还是 C,正式交付仍以”改仓库 skillpacks/ + opencode.json → 下一次 package.sh 全量包”为准;打包门禁 verify_skill_registration 会校验注册面一致性。

步骤三:验证结果

  • 技能市场:刷新页面,应能看到技能卡片(标题即 SKILL.md 里的 name)。
  • 命令行核对:
  • Agent 调用:新建会话,用 description 里的触发场景提问,确认 Agent 能加载并执行。

常见问题

技能市场整片空白,连内置技能都没有? 这通常不是你的技能没部署,而是授权缺少 skills_basic 模块:技能市场接口需要登录且校验该 授权模块,未授权时返回空列表且不报错。请检查目标机授权是否包含”技能”能力。 市场能看到,但对话里 Agent 不用它? 说明只完成了链路①。请确认已在 skills.paths 登记、并按”重启 gisagent → 重建运行实例 → 新建 会话”的顺序生效;用新会话再试。 改了 opencode.json 但没生效? 运行配置由打包阶段的同步逻辑从 opencode.json 生成到 OPENCODE_CONFIG_CONTENT,必须重新打包 (方式 A),或在目标机直接改挂载 profile 并定向重启(方式 B),或走 L0+L1 热更包(方式 C)才会 被读到。 opencode debug skill 能看到技能,但 Web UI 聊天里 Agent 不用它? Web UI 每个会话启动临时容器,其 OPENCODE_CONFIG_CONTENT 来自 gisagent 挂载的 config/local/agent.local-*.json(→ /workspace/config/agent.json),不是仓库的 config/opencode/opencode.json。开发机修复:更新 agent.local-*.json 的 OPENCODE_CONFIG_CONTENT(加入新技能路径),然后 docker compose restart gisagent, 再新建会话。 技能需要联网(调用公网 API)? 纯离线 / 局域网环境下不可用。此类依赖需在离线部署手册里明确标注,不能默认算作离线可用能力。 技能想带独立存储 / 特殊挂载? 少数内置技能(如 ui-ux-pro-max、geology-knowledge)使用独立 volume 与独立同步服务。新技能 一般走默认的 skillpacks-volume 即可;确需独立 volume 时参见下方设计规范。

下一步

  • 需要扩展 MCP(Model Context Protocol)服务、独立 volume、联网判定等更复杂场景,参考工程 规范文档 openspecs/changes/docker-skill-mcp-extension/(含可扩展的”验证台账 / 场景用例”)。
  • 热更框架的分级模型(L0~L3)、manifest 契约与回滚语义:参考 openspecs/changes/docker-hot-update/;MCP 侧的热加见添加自定义 MCP 的”已部署环境就地热加”。
  • 技能与运行期整体架构:参见 技能详细更新日志 与 使用技巧。