> ## Documentation Index
> Fetch the complete documentation index at: https://gisagent.mapgis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 添加自定义技能

> 在 GIS Agent（含离线部署）中新增一个自定义 SKILL 的完整教程：概念、两条生效链路、开发机步骤、离线目标机部署、L0+L1 热更新与常见问题。

# 如何添加一个自定义技能（SKILL）

本教程说明如何在 GIS Agent 中新增一个自定义技能，并让它在**技能市场**中可见、在**对话**中可被
Agent 调用。适用于本机开发环境，也适用于**离线 / 内网部署**的目标机。

阅读对象：需要给 GIS Agent 扩展新能力（新技能）的实施或开发人员。你不需要改任何构建脚本，
绝大多数情况下只是"放一个文件夹 + 跑一条同步命令"。

## 先理解：一个技能是什么

一个技能（SKILL）就是仓库 `skillpacks/` 下的一个目录，目录里至少有一个 `SKILL.md`：

```text theme={null}
skillpacks/
└── my-custom-skill/
    └── SKILL.md        # 必需：技能定义（frontmatter + 说明）
```

`SKILL.md` 顶部用 frontmatter 声明技能的 `name` 与 `description`：

```markdown theme={null}
---
name: my-custom-skill
description: 一句话说明这个技能做什么、以及用户提到哪些关键词时应当使用它。
---

# My Custom Skill

给 Agent 看的正文：何时使用、具体步骤、输出约定、边界。
```

* `name`：技能唯一标识，也是技能市场卡片的标题。用小写字母、数字、连字符。
* `description`：Agent 判断"什么时候该用这个技能"的依据，务必写清**用途 + 触发场景**。
* 正文：写给 Agent 的操作指引，越具体越稳定。技能可以引用同目录下的脚本、模板等文件。

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

新增技能时最容易踩的坑，是把"市场里看得见"和"对话里用得上"当成同一件事。它们是**两条独立
链路**：

| 目标 | 靠什么生效 | 前置条件 |
| - | - | - |
| ① 技能市场可见 | 技能文件同步进运行卷 `/workspace/skills`（系统递归扫描 `SKILL.md`） | 已登录 + 授权包含 `skills_basic` 模块 |
| ② Agent 对话可调用 | 在**生效载体**的 `skills.paths` 登记该目录：打包路径是 `config/opencode/opencode.json`（经 `package.sh` 同步进 profile），热更路径是直接改挂载 profile `config/local/agent.local-*.json` | 重启 gisagent（+ agent-opencode）+ 新建会话 |

一句话结论：

> **只要文件进了卷，技能市场就能看到；要让 Agent 在对话里真正用上它，还需要登记 `skills.paths`。**

## 步骤一：在开发机（仓库）里创建技能

### 1. 从模板工程开始（推荐）

官方在 `gisagent/custom/skill/hello-gis/` 提供了一个**最小但完整的 SKILL 模板工程**，包含：

* `SKILL.md`：frontmatter + 触发词 + 调用行为
* `scripts/hello.sh`：辅助脚本（演示 SKILL 如何引用目录内文件）
* `README.md`：说明与改造建议

你可以直接复制这个目录改造成自己的技能：

```bash theme={null}
# 复制模板工程
cp -a gisagent/custom/skill/hello-gis skillpacks/my-custom-skill

# 编辑 SKILL.md，修改 name、description、行为
vim skillpacks/my-custom-skill/SKILL.md
```

`SKILL.md` 顶部用 frontmatter 声明技能的 `name` 与 `description`：

```markdown theme={null}
---
name: my-custom-skill
description: 一句话说明这个技能做什么、以及用户提到哪些关键词时应当使用它。
---

# My Custom Skill

给 Agent 看的正文：何时使用、具体步骤、输出约定、边界。
```

* `name`：技能唯一标识，也是技能市场卡片的标题。用小写字母、数字、连字符。
* `description`：Agent 判断"什么时候该用这个技能"的依据，务必写清**用途 + 触发场景**。
* 正文：写给 Agent 的操作指引，越具体越稳定。技能可以引用同目录下的脚本、模板等文件。

> **参考实现**：`skillpacks/mapgis-custom-skill/` 是另一个常驻参考（纯 `SKILL.md` 无脚本版本），
> `skillpacks/hello-gis/` 是带辅助脚本的版本。两者都可用于验证扩展链路。

### 2. 登记到 `skills.paths`（仅"对话可调用"需要）

编辑 `config/opencode/opencode.json`，在 `skills.paths` 数组追加一行：

```json theme={null}
{
  "skills": {
    "paths": [
      "/workspace/skills/postgis-cli",
      "...其它已有技能...",
      "/workspace/skills/hello-gis"
    ]
  }
}
```

> 路径是**容器内路径**，固定以 `/workspace/skills/<技能目录名>` 开头，目录名要和第 1 步一致。
> 如果只需要技能市场显示、不需要对话调用，这一步可以省略。

### 3. 本机快速验证（可选，免重打包）

```bash theme={null}
docker exec agent-opencode sh -lc 'cd /workspace && opencode debug skill'
```

在输出里能看到你的技能 `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`，再验证：

  ```bash theme={null}
  docker exec agent-opencode python3 -c 'import json,io; p="/home/agent/.config/opencode/opencode.json"; d=json.load(open(p)); ps=d.setdefault("skills",{}).setdefault("paths",[]); [ps.append("/workspace/skills/hello-gis") for x in [0] if "/workspace/skills/hello-gis" not in ps]; json.dump(d,open(p,"w"))'
  docker exec agent-opencode sh -lc 'cd /workspace && opencode debug skill'
  ```

  验证后可把这条临时路径从容器配置里删掉；正式生效仍以改仓库 `config/opencode/opencode.json`
  并重打包为准。

## 步骤二：部署到目标机

有两种方式，按需选择。

### 方式 A：重新打包 offline bundle 再部署（推荐，交付用）

在开发机改完第 1、2 步后，直接重新打包。`package.sh` 会：

* 把 `skillpacks/` 整个目录**原样**拷进 bundle（**不需要改 `package.sh`**，新技能自动进包）；
* 把 `opencode.json` 的 `skills.paths` / `mcp` 同步进运行配置，供 Agent 读取。

```bash theme={null}
# 仓库根执行
./package.sh
# 然后把生成的 bundle 拷贝到目标机，按离线部署手册正常 deploy
```

### 方式 B：在已部署的目标机上就地添加（调试 / 增量交付）

适合目标机已经跑起来、只想快速加一个技能。技能市场显示（链路①）**只需做完前三步**。

在目标机的 bundle 目录下执行：

```bash theme={null}
cd /opt/gisagent/<你的-bundle-目录>      # 即 GISAGENT_HOST_BUNDLE_ROOT 指向的目录

# 1) 放入技能文件（直接创建，不要用批量替换脚本，避免误伤同名文件）
mkdir -p skillpacks/hello-gis
cat > skillpacks/hello-gis/SKILL.md <<'EOF'
---
name: hello-gis
description: GIS 问候技能模板。当用户提到 hello-gis、自定义技能、或要求确认技能扩展链路时使用；被调用时运行辅助脚本回显标记 HELLO_GIS_OK 并简述其用途，无业务副作用。
---

# Hello GIS Skill（GIS 问候技能模板）

用于验证 GISAgent 离线部署下的技能扩展链路：技能市场可见 + agent 可加载调用。

## 何时使用

- 用户提到 `hello-gis` 或"自定义技能"
- 需要确认技能市场 / agent 技能加载是否生效
- 演示 SKILL 如何引用目录内辅助脚本

## 行为

被调用时，运行本目录下的 `scripts/hello.sh` 脚本（传入调用者名字），原样回显标记串
`HELLO_GIS_OK`，并说明"该技能来自 hello-gis 自定义技能扩展验证"。
本技能不读写业务数据、不产生副作用。

## 辅助脚本

- `scripts/hello.sh <name>`：输出一行 `HELLO_GIS_OK · name=<name> · ts=<ISO8601>`，
  用于验证 SKILL 可以引用目录内文件并执行 shell 命令。
EOF

# 可选：放入辅助脚本
mkdir -p skillpacks/hello-gis/scripts
cat > skillpacks/hello-gis/scripts/hello.sh <<'EOF'
#!/usr/bin/env bash
# hello-gis 辅助脚本
# 用法: ./hello.sh [name]
# 输出: HELLO_GIS_OK · name=<name> · ts=<ISO8601>

set -euo pipefail

NAME="${1:-GIS}"
TS="$(date -Iseconds)"

printf 'HELLO_GIS_OK · name=%s · ts=%s · 该技能来自 hello-gis 自定义技能扩展验证。\n' "$NAME" "$TS"
EOF
chmod +x skillpacks/hello-gis/scripts/hello.sh

# 2) 同步进只读运行卷（skillpacks-sync 会从 ./skillpacks 全量重建卷，内置技能仍在源目录，安全）
docker compose run --rm skillpacks-sync

# 3) 确认文件已经进卷
docker exec mapgis-ai-gisagent sh -lc 'ls -l /workspace/skills/hello-gis/SKILL.md'
```

到这里，**刷新一次技能市场页面就能看到新技能**（链路①完成）。

若还要让 Agent 在对话里用上它（链路②），继续第 4 步登记 `skills.paths`。注意**改对载体**：
运行实例（含 Web UI 临时容器）读的是挂载 profile `config/local/agent.local-*.json` 里
`OPENCODE_CONFIG_CONTENT` 的 `skills.paths`，不是 bundle 的 `config/opencode/opencode.json`
（后者是打包期源文件）：

```bash theme={null}
# 4) 备份后，编辑 config/local/agent.local-*.json（${GISAGENT_AGENT_CONFIG} 指向的活跃
#    profile），在其 runtime.env.OPENCODE_CONFIG_CONTENT（内嵌 JSON 字符串）的
#    skills.paths 数组追加 "/workspace/skills/hello-gis"；
#    agent-opencode 与 agent-claude 两个块都要加。
#    同时把同一条路径补进 config/opencode/opencode.json，避免下次重打包丢失。

# 5) 定向重启生效服务，不动其它容器
docker compose restart gisagent agent-opencode
```

> 生效顺序固定为：**改配置 → 定向重启 gisagent（+ agent-opencode）→ 新建会话**。旧会话会缓存
> 技能快照，务必用新会话验证。

### 方式 C：热更包（L0+L1，带备份与健康闸门，推荐现场增量）

上面的方式 B 手工步骤，对应 `docker-hot-update` 框架的两层：**L0** 刷卷（免重启，等价
`skillpacks-sync`），**L1** 配置热更（profile 的 `skills.paths` + 定向 restart）。用框架脚本
可以把"改哪份载体、漏没漏重启"这类人为事故变成自动化：

```bash theme={null}
# 开发机：技能目录 + 改好的 profile 打进一个 L0 包 + 一个 L1 包
bash scripts/package-hotfix.sh --layer L0 --skills hello-gis
bash scripts/package-hotfix.sh --layer L1 \
  --config config/local/agent.local-qwen-fable.json:config/local/agent.local-qwen-fable.json \
  --restart gisagent,agent-opencode \
  --http-check http://<GISAgent主机>:17076/gis/:200

# 目标机：bundle 已内置 scripts/hot-update.sh（执行机需 python3 + PyYAML）
bash scripts/hot-update.sh --package gisagent-hotfix-L0-<日期>-<序号>.tar.gz \
  --stack-dir /opt/gisagent/<你的-bundle-目录>
bash scripts/hot-update.sh --package gisagent-hotfix-L1-<日期>-<序号>.tar.gz \
  --stack-dir /opt/gisagent/<你的-bundle-目录>
```

执行器自带 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`）。
* **命令行核对**：
  ```bash theme={null}
  docker exec mapgis-ai-gisagent sh -lc 'ls /workspace/skills'
  ```
* **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](https://gisagent.mapgis.com/docs/custom-mcp-tutorial.md)
  的"已部署环境就地热加"。
* 技能与运行期整体架构：参见 [技能详细更新日志](https://gisagent.mapgis.com/docs/skills-detailed-update-log.md) 与
  [使用技巧](https://gisagent.mapgis.com/docs/usage-tips.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.