如何添加一个自定义技能(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 目录下执行: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)。用框架脚本
可以把”改哪份载体、漏没漏重启”这类人为事故变成自动化:
<栈目录>/.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 时参见下方设计规范。