znlgis 博客

GIS开发与技术分享 — GDAL · GeoServer · PostGIS · QGIS · OpenLayers · Cesium · FreeCAD · NPOI

第四章：AI 工具集成指南

本章是面向 opengis-skills 用户的实用指南，详细讲解如何在各种主流 AI 编程工具中集成和使用 opengis-skills 的技能文件。无论你日常使用 Claude Code、Cursor、Cline、Copilot Chat 还是 OpenCode，都能在本章找到对应的配置方法和最佳实践。

4.1 前置准备

在使用 opengis-skills 之前，先把仓库放置到 AI 工具能够访问的位置。这一步虽然简单，但路径选择会直接影响后续长期使用的便利性和可维护性。

4.1.1 克隆仓库

核心仓库地址：https://github.com/znlgis/opengis-skills

直接克隆（适合个人/独立项目）：

# 克隆到当前项目根目录
git clone https://github.com/znlgis/opengis-skills.git

# 或克隆到用户全局目录
git clone https://github.com/znlgis/opengis-skills.git ~/opengis-skills

作为 Git Submodule（推荐，适合团队协作）：

# 在项目根目录执行
git submodule add https://github.com/znlgis/opengis-skills.git opengis-skills

# 之后别人 clone 你的项目时，需要初始化 submodule
git submodule update --init --recursive

使用 submodule 的好处：

  • 版本锁定：团队成员使用的是同一批 Skill 文件，避免因各自本地文件不一致导致的 AI 输出差异
  • CI/CI 友好：可以在流水线中复现同样的 AI 辅助编码环境
  • 可回滚：如果上游更新引起了问题，一个 git checkout 就能回到上一版本

4.1.2 路径建议

放置策略 路径示例 适用场景 优缺点
项目内 submodule <project>/opengis-skills/ 团队协作、需要版本锁定的项目 新人 onboarding 成本低，CI 一致性好
项目内平级目录 <project>/skills/ 项目内可能有多个 Skill 来源 需要额外管理路径，但更灵活
用户全局目录 ~/.ai-skills/opengis-skills/ 个人跨项目使用，不关心版本锁定 一处维护，全局可用，但不同电脑需要手动同步
固定工作区根目录 ~/workspace/opengis-skills/ 单机开发者，所有项目都在同一个 workspace 下 形成肌肉记忆，@路径固定，输入快

核心原则：选定一种放置策略后，在所有项目中保持一致。这样 @操作形成肌肉记忆后，不需要每次都回忆路径。推荐新手用「项目内 submodule」方式；老手如果有固定工作区习惯，可以放全局路径。

4.1.3 验证可访问性

放置好后，在 AI 工具中快速测试一下路径是否可达。以 Claude Code 为例：

# 启动 Claude Code 后输入
@opengis-skills/SKILL.md 列出 GIS 分类下有哪些技能

如果能正常加载并列出技能列表，说明路径配置正确。

4.2 Claude Code（最常用）

Claude Code 是 Anthropic 官方的终端 AI 编码工具，也是 对 SKILL.md 原生支持最完善的工具。它直接识别并通过 Skill 的 description 字段完成自动匹配，实现按需加载。目前在所有工具中的使用量稳居第一，因此本节内容最为详尽。

4.2.1 基本加载方式

Claude Code 使用 @ 引用语法加载本地的 SKILL.md 文件：

# 加载全局入口（推荐首次使用时加载）
@opengis-skills/SKILL.md

# 加载特定分类的二级索引
@opengis-skills/gis/SKILL.md              # GIS 所有技能一览
@opengis-skills/cad/SKILL.md              # CAD 所有技能一览
@opengis-skills/csharp/SKILL.md           # C# 框架技能一览
@opengis-skills/ai/SKILL.md               # AI 工具技能一览
@opengis-skills/iot/SKILL.md              # IoT 技能一览
@opengis-skills/3d/SKILL.md               # 3D 技能一览

# 加载具体项目技能（L3 层级）
@opengis-skills/gis/gdal/SKILL.md         # GDAL 命令行技能
@opengis-skills/gis/geoserver/SKILL.md     # GeoServer 地图服务器技能
@opengis-skills/gis/postgis/SKILL.md       # PostGIS 空间数据库技能
@opengis-skills/gis/cesiumjs/SKILL.md      # CesiumJS 3D 地球
@opengis-skills/gis/openlayers/SKILL.md    # OpenLayers Web 地图
@opengis-skills/gis/geopandas/SKILL.md     # GeoPandas 空间数据处理
@opengis-skills/gis/jts/SKILL.md           # JTS 几何引擎
@opengis-skills/gis/shapely/SKILL.md       # Shapely 几何运算
@opengis-skills/cad/freecad/SKILL.md       # FreeCAD 参数化建模
@opengis-skills/cad/clipper2/SKILL.md      # Clipper2 布尔运算

4.2.2 配置 .claude/settings.json

Claude Code 支持在项目级别通过 .claude/settings.json 配置自动加载的技能路径。这是最省心的配置方式——定义一次之后，每次对话 ChatGPT 都能自动发现技能。

项目内的 .claude/settings.json：

{
  "skills": {
    "paths": ["opengis-skills"]
  }
}

配置完成后，Claude Code 会自动扫描 opengis-skills/ 下所有子目录中的 SKILL.md 文件，并根据对话内容智能匹配。不需要每次手动 @加载。

全局配置（对所有项目生效）：

# 在 ~/.claude/settings.json 中配置
{
  "skills": {
    "paths": ["~/opengis-skills"]
  }
}

注意：全局配置和项目配置可以共存，Claude Code 会合并两者。如果路径指向同一仓库，项目级覆盖全局级。

4.2.3 CLAUDE.md 集成

CLAUDE.md 是项目根目录下给 Claude Code 全局指令的 Markdown 文件。可以在其中写入 GIS 相关的提示，让 Claude 在进入项目时就知道技能库的存在：

# CLAUDE.md

## GIS 技能库
本项目已集成 opengis-skills 技能库。在以下场景中，请主动加载对应技能：

### 空间数据处理
- GDAL 命令行操作：@opengis-skills/gis/gdal/SKILL.md
- Python 空间分析：@opengis-skills/gis/geopandas/SKILL.md
- 几何运算：@opengis-skills/gis/shapely/SKILL.md
- 空间数据库：@opengis-skills/gis/postgis/SKILL.md

### 地图服务与可视化
- 地图服务器搭建：@opengis-skills/gis/geoserver/SKILL.md
- Web 2D 地图：@opengis-skills/gis/openlayers/SKILL.md
- Web 3D 地球：@opengis-skills/gis/cesiumjs/SKILL.md

### CAD / 3D
- 参数化建模：@opengis-skills/cad/freecad/SKILL.md
- 二维布尔运算：@opengis-skills/cad/clipper2/SKILL.md
- DWG 解析：@opengis-skills/cad/libredwg/SKILL.md

### C# 开发
- .NET Web 框架：@opengis-skills/csharp/furion/SKILL.md
- ORM 操作：@opengis-skills/csharp/sqlsugar/SKILL.md
- Office 读写：@opengis-skills/csharp/npoi/SKILL.md

### 加载策略
- 不确定用哪个工具时：先加载 @opengis-skills/SKILL.md 全局索引
- 确定大类（如 GIS）时：加载 @opengis-skills/gis/SKILL.md 分类索引
- 确定具体工具时：直接加载该工具的 SKILL.md

这样，每次在项目下启动 Claude Code，CLAUDE.md 都会被加载，Claude 就能在合适的时机自动引用 opengis-skills。

4.2.4 主动与被动加载策略

Claude Code 的技能加载分两种模式：

主动加载（Explicit Loading）——用户明确 @引用：

用户：@opengis-skills/gis/gdal/SKILL.md 帮我把 data/*.tif 转成 COG 格式

此时 Claude 会加载 GDAL 技能的完整内容到当前对话上下文，然后基于技能中记录的 gdal_translate -of COG 命令生成准确的指令。

被动匹配（Auto-Matching）——配置了 skills.paths 后自动触发：

用户：帮我把 Shapefile 转成 GeoJSON

Claude Code 扫描配置的 Skill 路径，匹配到 GDAL 技能的 description 中包含 vector data conversion 相关触发词，自动加载 GDAL 技能，然后给出 ogr2ogr -f GeoJSON output.geojson input.shp 命令。用户全程无需手动 @引用。

推荐策略：

场景 使用方式 理由
日常高频操作 配置 skills.paths，依赖被动匹配 省心，自动识别
精度要求高的任务 手动 @引用确保加载了正确的技能 避免匹配到相似但不准确的技能
跨领域组合任务 先 @加载全局索引 SKILL.md，再按定位结果逐步 @加载具体技能 确保不遗漏
第一次使用某个工具 手动 @加载完整的 SKILL.md 通读 了解工具全貌后再提具体问题

4.2.5 实际操作示例

以下是几个完整的 Claude Code 对话示例，展示 opengis-skills 在实际工作中的使用方式。

示例一：GDAL 影像裁剪

用户：@opengis-skills/gis/gdal/SKILL.md 帮我把 data/*.tif 裁剪到 AOI.geojson 范围内

Claude：[加载 GDAL 技能...]
       根据 GDAL 技能记录的 gdalwarp 用法，使用以下命令：
       
       gdalwarp -cutline AOI.geojson -crop_to_cutline data/input.tif data/output.tif
       
       - -cutline AOI.geojson：指定裁剪边界矢量文件
       - -crop_to_cutline：将输出栅格裁切到裁剪范围
       
       如果有多个 .tif 文件，可以用批处理：
       for %f in (data\*.tif) do gdalwarp -cutline AOI.geojson -crop_to_cutline "%f" "output\%~nf_clipped.tif"

用户：GeoJSON 里是 EPSG:4326，但 .tif 是 EPSG:3857 的，需要重投影吗？

Claude：gdalwarp 会自动处理投影转换，因为 GDAL 支持从 -cutline 的坐标系到目标栅格的
       坐标系进行自动重投影。你也可以显式指定：
       
       gdalwarp -cutline AOI.geojson -crop_to_cutline -t_srs EPSG:3857 data/input.tif data/output.tif

示例二：GeoServer 样式发布

用户：@opengis-skills/gis/geoserver/SKILL.md 我有一个 PostGIS 里的 roads 表，如何通过 REST API
      发布成 WMS 服务并设置线宽颜色？

Claude：[加载 GeoServer 技能...]
       通过 GeoServer REST API 分三步完成：
       
       1. 创建工作区（如果还没有）
          curl -u admin:geoserver -X POST \
            -H "Content-Type: application/json" \
            -d '{"workspace":{"name":"myworkspace"}}' \
            http://localhost:8080/geoserver/rest/workspaces
       
       2. 发布 PostGIS 图层
          curl -u admin:geoserver -X POST \
            -H "Content-Type: application/xml" \
            -d '<featureType><name>roads</name><nativeName>roads</nativeName>
                <srs>EPSG:4326</srs></featureType>' \
            http://localhost:8080/geoserver/rest/workspaces/myworkspace/datastores/postgis/featuretypes
       
       3. 设置 SLD 样式（线宽=2，蓝色）
          curl -u admin:geoserver -X PUT \
            -H "Content-Type: application/vnd.ogc.sld+xml" \
            -d '<StyledLayerDescriptor>...</StyledLayerDescriptor>' \
            http://localhost:8080/geoserver/rest/styles/roads_style
       
       详细的 SLD 写法请参考 GeoServer 技能中的「样式配置」章节。

示例三：多技能组合工作流

用户：@opengis-skills/gis/SKILL.md 我要做一个功能：前端用 OpenLayers 显示地图，后端用 PostGIS 存储
      空间数据，通过 GeoServer 发布 WMS 服务。帮我理一下技术方案。

Claude：[加载 GIS 分类索引...]
       根据 GIS 技能索引，你的技术栈覆盖了三个技能：
       - @opengis-skills/gis/geoserver/SKILL.md（地图服务发布）
       - @opengis-skills/gis/postgis/SKILL.md（空间数据存储）
       - @opengis-skills/gis/openlayers/SKILL.md（Web 前端展示）
       
       整体架构：PostGIS → GeoServer → OpenLayers
       
       需要我逐个加载这三个技能给出详细实现吗？

4.3 Cursor

Cursor 是基于 VS Code 的 AI 编程 IDE，对文件引用系统支持完善，但不原生支持 Skill 的 description 自动匹配机制。主要通过 @file 语法和 .cursorrules 文件实现集成。

4.3.1 直接加载方式

在 Cursor 的 AI 对话栏中，使用 @file 语法引用 SKILL.md：

@file:opengis-skills/SKILL.md                   # 加载全局索引
@file:opengis-skills/gis/gdal/SKILL.md           # 加载 GDAL 技能
@file:opengis-skills/gis/geoserver/SKILL.md      # 加载 GeoServer 技能

也可以用 @folder 让 Cursor 理解整个技能目录的结构：

@folder:opengis-skills/gis/  # 让 Cursor 了解 GIS 技能全部内容

@folder 的优势是一次性注入整个目录下的文件作为上下文，缺点是如果目录下有多个文件，上下文占用会比较大。对于 opengis-skills，每个技能目录通常只有一个 SKILL.md 文件（部分如 GDAL 有 reference/ 子目录），@file 更精准。

4.3.2 .cursorrules 配置

在项目根目录创建 .cursorrules 文件，为 Cursor 的项目级 AI 提供持久化的上下文规则：

# .cursorrules

## GIS Development
本项目已集成 opengis-skills 技能库。在处理地理空间任务时，请参考以下技能文件：

### 空间数据处理
- 矢量/栅格转换与处理：@file:opengis-skills/gis/gdal/SKILL.md
- Python 空间分析：@file:opengis-skills/gis/geopandas/SKILL.md
- 几何对象运算：@file:opengis-skills/gis/shapely/SKILL.md
- Java 几何引擎：@file:opengis-skills/gis/jts/SKILL.md
- .NET 几何引擎（JTS 移植）：@file:opengis-skills/gis/nettopologysuite/SKILL.md

### 地图服务
- 地图服务器搭建与配置：@file:opengis-skills/gis/geoserver/SKILL.md
- GeoServer REST API 自动化：@file:opengis-skills/gis/geoserver-rest-api/SKILL.md
- QGIS Python 开发：@file:opengis-skills/gis/pyqgis/SKILL.md
- QGIS 批处理：@file:opengis-skills/gis/qgis-process/SKILL.md

### 前端可视化
- Web 2D 地图：@file:opengis-skills/gis/openlayers/SKILL.md
- Web 3D 地球：@file:opengis-skills/gis/cesiumjs/SKILL.md
- .NET 地图控件：@file:opengis-skills/gis/mapsui/SKILL.md

### CAD 开发
- 参数化 3D 建模：@file:opengis-skills/cad/freecad/SKILL.md
- 2D 布尔运算：@file:opengis-skills/cad/clipper2/SKILL.md
- DWG/DXF 读写：@file:opengis-skills/cad/libredwg/SKILL.md
- .NET BIM 工具：@file:opengis-skills/cad/xbim/SKILL.md

### C# 后端
- 企业级 Web 框架：@file:opengis-skills/csharp/furion/SKILL.md
- 多数据库 ORM：@file:opengis-skills/csharp/sqlsugar/SKILL.md
- Excel/Word 读写：@file:opengis-skills/csharp/npoi/SKILL.md

### AI 工具
- Dify 平台：@file:opengis-skills/ai/dify/SKILL.md
- OpenCode 配置：@file:opengis-skills/ai/opencode/SKILL.md
- Ai 编程方法论：@file:opengis-skills/ai/superpowers-zh/SKILL.md

注意：.cursorrules 会被注入到每一次 Cursor 对话中。不要在其中粘贴 SKILL.md 的完整内容——这会让每次对话都携带大量冗余上下文，降低 AI 效率。只写引用路径和简短说明，让 Cursor 按需通过 @file 获取实际内容。

4.3.3 Settings → Rules for AI

Cursor 的 Rules for AI 功能位于 Settings → General → Rules for AI，支持配置全局或项目级别的 AI 行为规则。与 .cursorrules 的区别在于：

特性 .cursorrules Rules for AI
存放位置 项目根目录文件 Cursor 设置界面
适用范围 当前项目 可设为全局或项目级
版本控制 可提交 Git（推荐） 不可提交
编辑方式 文本编辑器 UI 界面
推荐用途 团队共享的项目规则 个人偏好和实验性规则

对于 opengis-skills，推荐在 .cursorrules 中维护引用规则（便于团队共享），在 Rules for AI 中维护个人工作习惯（如「GIS 任务时先加载全局索引」）。

4.4 Cline / Roo Code（VS Code）

Cline 和 Roo Code 是两个在 VS Code 生态中非常流行的 AI 编码插件，都支持通过 @ 语法加载本地文件和 .clinerules 规则文件。

4.4.1 基本加载方式

在 Cline / Roo Code 的对话框中：

@opengis-skills/SKILL.md                # 全局入口
@opengis-skills/gis/gdal/SKILL.md        # GDAL 技能
@opengis-skills/gis/geoserver/SKILL.md   # GeoServer 技能

Cline / Roo Code 的 @ 语法会直接将文件内容注入到当前对话上下文中。和 Claude Code 的区别是，它们不会根据 description 字段自动匹配技能——需要用户明确知道要加载哪个文件。

4.4.2 .clinerules 配置

.clinerules 是 Cline / Roo Code 的项目级规则文件，类似 Cursor 的 .cursorrules。在项目根目录创建：

# .clinerules

## GIS Development Skills
You have access to opengis-skills knowledge base at opengis-skills/
When user asks about GIS tools, read relevant SKILL.md files first.

### Available Skills
When any of these topics come up, load the corresponding SKILL.md:

| User Mentions | Load This File |
|--------------|----------------|
| GDAL, ogr2ogr, gdalwarp, raster, vector conversion | @opengis-skills/gis/gdal/SKILL.md |
| GeoServer, WMS, WFS, WCS, SLD, map server | @opengis-skills/gis/geoserver/SKILL.md |
| PostGIS, spatial database, ST_ functions | @opengis-skills/gis/postgis/SKILL.md |
| GeoPandas, Python shapefile, geodataframe | @opengis-skills/gis/geopandas/SKILL.md |
| Shapely, geometry, intersection, buffer | @opengis-skills/gis/shapely/SKILL.md |
| JTS, Java geometry, topology | @opengis-skills/gis/jts/SKILL.md |
| CesiumJS, 3D globe, Cesium | @opengis-skills/gis/cesiumjs/SKILL.md |
| OpenLayers, web map, ol, tile layer | @opengis-skills/gis/openlayers/SKILL.md |
| FreeCAD, parametric CAD, Python CAD | @opengis-skills/cad/freecad/SKILL.md |
| OCCT, Open CASCADE, 3D kernel | @opengis-skills/cad/occt/SKILL.md |
| Clipper2, polygon boolean, offset | @opengis-skills/cad/clipper2/SKILL.md |
| Furion, .NET web framework | @opengis-skills/csharp/furion/SKILL.md |
| SqlSugar, .NET ORM, Chinese ORM | @opengis-skills/csharp/sqlsugar/SKILL.md |
| NPOI, Excel .NET, Word .NET | @opengis-skills/csharp/npoi/SKILL.md |
| Dify, LLM app platform, RAG | @opengis-skills/ai/dify/SKILL.md |
| OpenCode, AI terminal agent | @opengis-skills/ai/opencode/SKILL.md |

### Loading Strategy
1. If user's request clearly targets one tool → load that tool's SKILL.md directly
2. If user is unsure which tool to use → load @opengis-skills/SKILL.md (global index) first
3. If user needs end-to-end workflow → load relevant project SKILL.md files sequentially

4.4.3 Cline 自定义指令

Cline 支持在 Settings 中定义「Custom Instructions」，分为两条：

Instructions for File & Command Creation（创建文件时遵循的规则）：

GIS & Geospatial Development:
- Before generating GIS code, check opengis-skills/ for relevant SKILL.md files
- Use the API patterns and command examples documented in the skills
- Prefer GDAL CLI over custom scripts for batch processing
- Follow the coordinate system handling patterns from skills

Instructions for New Chats（新对话开始时注入的上下文）：

Available Skills Repository: opengis-skills/
- GIS tools: @opengis-skills/gis/SKILL.md
- CAD tools: @opengis-skills/cad/SKILL.md
- C# frameworks: @opengis-skills/csharp/SKILL.md
- AI tools: @opengis-skills/ai/SKILL.md

4.4.4 Roo Code 的 .roomodes

如果你使用 Roo Code，还可以通过 .roomodes 配置自定义模式（Modes），让特定模式自动加载特定技能。例如定义一个 GIS 模式：

{
  "customModes": [
    {
      "slug": "gis-dev",
      "name": "GIS Developer",
      "roleDefinition": "You are a GIS specialist. Always load @opengis-skills/gis/SKILL.md before answering spatial questions.",
      "groups": ["read", "edit", "command"]
    }
  ]
}

4.5 VS Code Copilot Chat

GitHub Copilot Chat 是 VS Code 内置的 AI 对话功能，其文件引用机制和 Cursor/Cline 略有不同，使用 #file: 语法。

4.5.1 基本加载方式

在 Copilot Chat 对话框中：

#file:opengis-skills/SKILL.md                  # 全局索引
#file:opengis-skills/gis/gdal/SKILL.md          # GDAL 技能
#file:opengis-skills/gis/geoserver/SKILL.md     # GeoServer 技能

Copilot Chat 也支持 @workspace 结合搜索整个工作区，但 opengis-skills 的 SKILL.md 文件内容较结构化，建议使用 #file: 精确加载而非让 Copilot 在工作区中模糊搜索。

4.5.2 项目级 Copilot 指令

在项目根目录创建 .github/copilot-instructions.md：

# GitHub Copilot Instructions

## GIS Development Skills
This project uses [opengis-skills](https://github.com/znlgis/opengis-skills) for geospatial development guidance.
The skills are located at `opengis-skills/`.

### When to Load Skills
- For **GDAL/OGR commands**: load `#file:opengis-skills/gis/gdal/SKILL.md` before generating CLI commands
- For **GeoServer configuration**: load `#file:opengis-skills/gis/geoserver/SKILL.md` before writing XML config
- For **PostGIS queries**: load `#file:opengis-skills/gis/postgis/SKILL.md` before writing spatial SQL
- For **Python geospatial**: load `#file:opengis-skills/gis/geopandas/SKILL.md` for vector processing
- For **Java GIS**: load `#file:opengis-skills/gis/jts/SKILL.md` for geometry operations
- For **Web 2D maps**: load `#file:opengis-skills/gis/openlayers/SKILL.md` for frontend rendering
- For **Web 3D visualization**: load `#file:opengis-skills/gis/cesiumjs/SKILL.md` for CesiumJS

### General Principles
- Never guess API signatures — always reference the SKILL.md first
- The SKILL.md files contain verified code examples from official documentation
- If multiple tools could solve a problem, consult the global index at `#file:opengis-skills/SKILL.md`
- Tag-based search is available in the global index for quick skill discovery

4.5.3 VS Code settings.json 自定义指令

在 VS Code 的 settings.json 中，可以为 Copilot Chat 添加全局或工作区级别的指令：

{
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "text": "When working with geospatial data: (1) Check opengis-skills/ directory for relevant SKILL.md files first. (2) Use the command patterns and API examples from the skills. (3) Prefer well-established patterns from GDAL, PostGIS, and GeoServer skills over custom implementations.",
      "file": ""
    }
  ],
  "github.copilot.chat.commitMessageGeneration.instructions": [
    {
      "text": "Use conventional commit format. If changes are GIS-related, include the tool name in scope (e.g., feat(gdal): ..., fix(postgis): ...).",
      "file": ""
    }
  ]
}

4.5.4 Copilot Participants

GitHub Copilot 引入了「Participants」概念（如 @workspace、@terminal 等），opengis-skills 可以搭配使用：

# 在工作区内搜索并加载 GDAL 技能，然后在终端执行命令
@workspace 查找矢量转栅格的 GDAL 命令，然后 @terminal 执行

# 只加载特定文件
#file:opengis-skills/gis/gdal/SKILL.md 帮我生成 Shapefile 转 GeoJSON 的命令

4.6 OpenCode

OpenCode 本身是 opengis-skills 中 ai/opencode/SKILL.md 覆盖的一个技能 —— 它是一个模型无关的终端 AI 编码代理，通过 opencode.json 实现「配置即代码」的理念。对于 opengis-skills 的集成，OpenCode 原生支持 Skill 路径扫描和自动加载。

4.6.1 配置 opencode.json

在项目根目录的 opencode.json 中添加技能路径配置：

{
  "skills": {
    "paths": ["opengis-skills"]
  },
  "instructions": {
    "project": [
      "对于 GIS 数据处理任务，先加载 @opengis-skills/gis/SKILL.md 了解可用技能",
      "对于 CAD 建模任务，先加载 @opengis-skills/cad/SKILL.md 了解可用技能",
      "对于 C# 后端开发，先加载 @opengis-skills/csharp/SKILL.md 了解可用框架",
      "对于 AI 工具配置，先加载 @opengis-skills/ai/SKILL.md 了解可用方案",
      "处理空间数据时，优先使用 GDAL/PostGIS/GeoServer 等标准工具",
      "编写 Python 空间分析代码时，参考 GeoPandas/Shapely 技能中的 API 示例",
      "不确定使用哪个工具时，先加载 @opengis-skills/SKILL.md 全局索引并通过标签搜索"
    ]
  }
}

OpenCode 的 skills.paths 配置和 Claude Code 机制相同：扫描指定目录下的所有 SKILL.md，根据 frontmatter 中的 description 字段进行被动匹配。

4.6.2 AGENTS.md 集成

AGENTS.md 是 OpenCode 的项目级全局规则文件（类似 Claude Code 的 CLAUDE.md）。在其中写入技能库的引用规则：

# AGENTS.md

## 技能库集成
本项目使用 [opengis-skills](https://github.com/znlgis/opengis-skills) 作为技能知识库。
技能文件位于 opengis-skills/ 目录下，采用三层索引结构。

### 三层加载策略

| 层级 | 文件 | 何时加载 |
|------|------|----------|
| L1 全局入口 | `opengis-skills/SKILL.md` | 不确定具体用哪个工具，或需要跨领域搜索时 |
| L2 分类索引 | `opengis-skills/gis/SKILL.md` 等 | 确定领域大类（GIS/CAD/C#/AI）但不确定具体工具时 |
| L3 项目技能 | `opengis-skills/gis/gdal/SKILL.md` 等 | 确定使用哪个具体工具，需要精确编码指导时 |

### 按需加载指南
- **GIS 任务**：`opengis-skills/gis/SKILL.md`（含 23 个 GIS 技能索引）
- **CAD 任务**：`opengis-skills/cad/SKILL.md`（含 18 个 CAD 技能索引）
- **C# 开发**：`opengis-skills/csharp/SKILL.md`（含 8 个 C# 框架技能索引）
- **AI 工具**：`opengis-skills/ai/SKILL.md`（含 8 个 AI 技能索引）
- **IoT 任务**：`opengis-skills/iot/SKILL.md`
- **3D 任务**：`opengis-skills/3d/SKILL.md`

### 守则
1. 永远不要在不确定 API 时靠记忆猜测 —— 先加载对应 SKILL.md
2. SKILL.md 中的代码示例来自官方文档验证，优先使用其中的模式
3. 跨领域问题时从 L1 全局入口开始逐个定位

4.6.3 OpenCode 的独特优势

与其他工具相比，OpenCode 在集成 opengis-skills 时有几个独特优势：

1. 模型无关性：OpenCode 支持接入多个模型提供商（Anthropic、DeepSeek、OpenAI 等）。opengis-skills 的 SKILL.md 内容丰富但通过三层索引实现了按需加载，不会过度膨胀上下文，所以即使使用上下文窗口较小的模型（如 128K），也能高效工作。

2. 多 Agent 协同：OpenCode 的 Agent 体系允许为不同任务分派不同的子代理。例如，GIS 任务分派给加载了 opengis-skills/gis/SKILL.md 的子代理，CAD 任务分派给加载了 opengis-skills/cad/SKILL.md 的子代理，二者互不干扰。

3. 配置即代码：opencode.json 和 AGENTS.md 都可以提交到 Git，团队成员克隆项目后自动获得相同的 Skill 配置，不需要手动安装或初始化。

4. Commands 自定义：可以为经常使用的技能创建自定义命令：

{
  "commands": {
    "gis-gdal": {
      "description": "Load GDAL skill and execute GDAL commands",
      "prompt": "@opengis-skills/gis/gdal/SKILL.md $ARGUMENTS"
    },
    "gis-pg": {
      "description": "Load PostGIS skill for spatial SQL",
      "prompt": "@opengis-skills/gis/postgis/SKILL.md $ARGUMENTS"
    },
    "cad-freecad": {
      "description": "Load FreeCAD skill for parametric modeling",
      "prompt": "@opengis-skills/cad/freecad/SKILL.md $ARGUMENTS"
    }
  }
}

然后在对话中使用：

/gis-gdal 把 data/*.shp 转成 GeoJSON
/gis-pg 帮我写一个查询所有在指定多边形内的道路的 SQL
/cad-freecad 创建一个参数化的螺栓模型

4.7 DeepSeek Chat

DeepSeek Chat（包括 Web 版和 API 版）的上下文窗口较大（128K），对中文支持出色，但对 SKILL.md 文件没有原生引用机制。需要通过文件上传或内容粘贴的方式将技能加载到对话中。

4.7.1 文件上传方式

DeepSeek Web Chat 支持文件上传功能。可以将 SKILL.md 文件作为附件上传到对话中：

  1. 在 Web 界面点击文件上传按钮
  2. 选择 opengis-skills/SKILL.md（全局索引）或其他具体技能的 SKILL.md
  3. 在对话中提问，DeepSeek 会基于上传的文件内容回答

推荐组合：一次上传可以包含多个文件。对于 DeepSeek Chat，建议：

  • 首次使用：上传 SKILL.md（全局入口，约 66 个技能的索引）作为基础参考
  • 具体任务：追加上传对应工具的 SKILL.md
  • 跨领域任务：上传分类 SKILL.md（如 gis/SKILL.md），然后按需追加具体技能

4.7.2 粘贴加载方式

对于 API 调用或无文件上传功能的环境，可以在对话开头粘贴 SKILL.md 的关键内容。推荐粘贴以下部分：

  1. YAML frontmatter（name、description、tags）——让 AI 了解这个技能是什么
  2. 概述章节——工具定位和核心特性
  3. 与当前问题相关的 API/命令示例——需要什么就贴什么
# 以下内容来自 opengis-skills/gis/gdal/SKILL.md

## GDAL/OGR —— 栅格/矢量数据处理事实标准

### 矢量转换
ogr2ogr -f GeoJSON output.json input.shp
ogr2ogr -f "PostgreSQL" PG:"dbname=mydb" input.shp

### 栅格处理
gdalwarp -cutline AOI.geojson -crop_to_cutline input.tif output.tif
gdal_translate -of COG input.tif output.tif

现在，请根据以上信息帮我把 data/roads.shp 转成 GeoJSON。

4.7.3 上下文优化：利用 128K 窗口

DeepSeek 的 128K 上下文窗口非常适合 opengis-skills 的三层索引架构。最佳实践：

Step 1：上传全局索引 SKILL.md，让 DeepSeek 了解 66 个技能的全貌。

Step 2：根据 DeepSeek 的推荐，上传对应分类的 SKILL.md（如 gis/SKILL.md）获取领域概要。

Step 3：上传具体工具的 SKILL.md 获取精确的 API 和命令示例。

这种渐进式加载策略充分利用了 DeepSeek 的大上下文优势，避免了在其他工具中可能遇到的上下文爆炸问题——因为 opengis-skills 的三层索引架构本身就从设计上控制了每个文件的大小，而不是把所有内容放一个文件里。

4.7.4 DeepSeek API 调用集成

如果通过 API 调用 DeepSeek，可以在 system prompt 中预加载技能内容：

import requests

# 读取需要的技能文件
with open("opengis-skills/gis/gdal/SKILL.md", "r", encoding="utf-8") as f:
    gdal_skill = f.read()

response = requests.post(
    "https://api.deepseek.com/v1/chat/completions",
    headers={"Authorization": "Bearer sk-xxx"},
    json={
        "model": "deepseek-chat",
        "messages": [
            {
                "role": "system",
                "content": f"你是一个 GIS 开发助手。以下是 GDAL 技能参考：\n\n{gdal_skill[:5000]}\n\n请基于这些知识回答用户问题。"
            },
            {
                "role": "user",
                "content": "帮我把 data/*.tif 转成 COG 格式"
            }
        ]
    }
)

注意：DeepSeek 的 system prompt 长度会占用上下文窗口。建议只注入与当前任务直接相关的 SKILL.md 的关键章节，而不是全文注入。对于 GDAL 这种有 reference/ 子目录拆分的技能，可以进一步精简注入内容。

4.8 GitHub Copilot（IDE）

GitHub Copilot 的 IDE 集成主要指在 VS Code / JetBrains 等编辑器中使用 Copilot 的代码补全和内联对话功能。由于内联对话的上下文限制，opengis-skills 的集成方式和全功能聊天工具有所不同。

4.8.1 Workspace 模式

GitHub Copilot 的 Workspace 模式可以从整个工作区搜索相关文件作为上下文。如果 opengis-skills 作为项目内 submodule 存在，Workspace 模式会在你提问时自动搜索并引用相关文件内容：

# 在 Copilot Edit 或 Chat 中
@workspace 帮我把 shapefile 转成 GeoJSON

Copilot 会在工作区中搜索包含 shapefile、GeoJSON、ogr2ogr 等关键字的文件，如果 opengis-skills 的 GDAL 技能文件包含相关内容，就会自动引用。

局限性：Workspace 搜索基于语义相似度，不一定能定位到最准确的 SKILL.md。对于精确度要求高的任务，建议使用 #file: 语法。

4.8.2 .github/copilot-instructions.md

在项目根目录创建此文件，为 Copilot 提供持久的项目级指令（详见 4.5.2 节的完整示例）。这个文件会被 Copilot 在每次对话和代码补全中加载。

对于 opengis-skills 用户，这个文件的核心内容是技能引用表——告诉 Copilot 在遇到什么样的用户问题时应该参考哪个 SKILL.md。关键是写得简洁，只包含路径映射，不粘贴技能内容。

4.8.3 代码补全中的应用

Copilot 的代码补全功能（inline suggestions）不支持直接加载完整 SKILL.md 文件作为补全上下文。但如果 .github/copilot-instructions.md 中提到了 opengis-skills 的路径和触发条件，Copilot 在生成代码补全时会考虑这些指令：

// 如果在 copilot-instructions.md 中配置了：
// "For spatial queries, reference patterns from opengis-skills/gis/postgis/SKILL.md"

// 那么当你在写 PostGIS 相关代码时，Copilot 的补全会倾向于使用
// 技能文件中记录的 ST_ 函数命名和参数模式

const query = `
  SELECT  -- Copilot 可能建议: id, ST_AsGeoJSON(geom) as geometry
  FROM roads
  WHERE ST_Within(  -- Copilot 可能建议: ST_Within(geom, ST_GeomFromGeoJSON($1))
`;

这种隐式影响虽然不如在聊天对话中显式 @加载那么强，但对于经常编写同类型代码的场景，确认 copilot-instructions.md 配置到位后，补全质量会有可感知的提升。

4.9 对比：各工具的集成能力

下表总结了 2026 年主流 AI 编程工具对 opengis-skills 的集成能力对比：

工具 @语法支持 文件引用方式 配置持久化 Skill自动匹配 推荐集成方式 适合场景
Claude Code 原生 @path/to/SKILL.md settings.json 原生支持 @语法 + settings.json 首选，对 Skill 支持最完善
Cursor @file @file:path/to/SKILL.md .cursorrules 不支持 @file + .cursorrules VS Code 用户的第二选择
Cline @语法 @path/to/SKILL.md .clinerules 不支持 @语法 + .clinerules VS Code 插件，轻量简洁
Roo Code @语法 @path/to/SKILL.md .clinerules / .roomodes 不支持 @语法 + .roomodes 需要多模式切换的场景
VS Code Copilot Chat #file: #file:path/to/SKILL.md .github/instructions 不支持 #file: + instructions VS Code 原生用户
OpenCode @语法 @path/to/SKILL.md opencode.json 原生支持 @语法 + opencode.json 追求模型无关配置的用户
DeepSeek Chat 无 上传文件 / 粘贴内容 无持久化 不支持 上传文件（128K 上下文） 中文场景、大上下文需求
GitHub Copilot IDE 间接 @workspace / #file: .github/instructions 不支持 @workspace + instructions 实时代码补全场景

关键差异解读

1. Skill 自动匹配（Passive Loading）：目前只有 Claude Code 和 OpenCode 支持基于 SKILL.md 中 description 字段的被动匹配。这意味着在这两个工具中，你不需要手动 @引用技能文件——只需描述需求，AI 会自动加载匹配的技能。其他工具都需要用户明确指定要加载哪个文件。

2. 配置持久化：Claude Code 的 settings.json、Cursor 的 .cursorrules、Cline/Roo Code 的 .clinerules、Copilot 的 .github/copilot-instructions.md、OpenCode 的 opencode.json 都是可提交 Git 的持久化配置文件，适合团队协作。DeepSeek Chat 没有等价机制，每次对话都需要重新上传或粘贴。

3. 与 VS Code 的集成深度：如果你的主力编辑器是 VS Code，Cursor 和 Cline/Roo Code 的体验会更无缝——它们作为 VS Code 插件，可以直接在编辑器中访问工作区文件。Claude Code 虽然更强大，但它是独立的终端工具，需要切换窗口。

选型建议

你的日常工具是 Claude Code ────→ 首选，原生 Skill 支持最好，直接用
你的日常工具是 VS Code ────────→ Cursor > Cline/Roo Code > Copilot Chat
你需要团队统一配置 ───────────→ Claude Code (settings.json) 或 OpenCode (opencode.json)
你主要用中文提问 ─────────────→ DeepSeek Chat（128K + 中文优化）或 Claude Code
你需要实时代码补全 ───────────→ GitHub Copilot (IDE) + .github/copilot-instructions.md
你追求配置即代码哲学 ─────────→ OpenCode

4.10 最佳实践建议

基于实际使用经验和社区反馈，以下是在各种 AI 工具中集成 opengis-skills 的最佳实践。

4.10.1 仓库位置原则

推荐方案：作为 Git Submodule 放在每个项目的 skills/ 或项目根目录下：

my-gis-project/
├── .claude/
│   └── settings.json       # Claude Code 技能路径配置
├── .cursorrules             # Cursor 规则
├── .clinerules              # Cline/Roo Code 规则
├── .github/
│   └── copilot-instructions.md
├── CLAUDE.md                # Claude Code 全局指令
├── AGENTS.md                # OpenCode 全局规则
├── opencode.json            # OpenCode 配置
├── opengis-skills/          # Git Submodule
│   ├── SKILL.md
│   ├── gis/
│   ├── cad/
│   ├── csharp/
│   ├── ai/
│   ├── iot/
│   ├── 3d/
│   └── others/
└── src/

为什么推荐 Submodule 而非直接 clone：

  1. 版本锁定：如果上游 opengis-skills 引入了不兼容的更新或实验性技能，你的项目不会受到影响。通过 git submodule update --remote 可以有意识地上拉更新。
  2. CI/CD 一致性：构建流水线中的 AI 工具访问的是和本地开发完全相同的 Skill 版本，避免「本地能跑，CI 跑不了」的问题。
  3. 团队统一：git clone --recursive 一条命令让新成员获得相同配置。
  4. 可回滚：上游更新后如果出现问题，cd opengis-skills && git checkout <old-commit> 轻松回退。

4.10.2 按需加载：L1 → L2 → L3 标准流程

这是 opengis-skills 三层索引架构的设计初衷——不要一次性加载所有技能。

第一问：不确定用哪个工具
    → 加载 L1: @opengis-skills/SKILL.md
    → 搜索标签（如 #conversion #vector）
    → 找到候选技能

第二问：确定了大类但不确定具体工具
    → 加载 L2: @opengis-skills/gis/SKILL.md
    → 浏览 23 个 GIS 技能概要
    → 选择最合适的工具

第三问：确定了具体工具
    → 加载 L3: @opengis-skills/gis/gdal/SKILL.md
    → 获取精确 API / 命令 / 工作流指导

反模式：把所有 SKILL.md 一次性粘贴到对话开头。这既浪费上下文（大模型注意力会被稀释），也可能造成「技能冲突」（不同工具的相似命令让 AI 产生混淆）。

4.10.3 本地化定制

如果你有团队或项目特定的需求，可以在本地 fork opengis-skills 后添加自定义技能：

my-opengis-skills/
├── SKILL.md                       # 保留上游全局索引
├── gis/                           # 上游 GIS 技能
├── custom/                        # 自定义团队技能目录
│   ├── SKILL.md                   # 自定义分类索引
│   ├── internal-gdal-workflow/    # 团队内部的 GDAL 工作流
│   │   └── SKILL.md
│   └── project-spec/              # 项目专属规范
│       └── SKILL.md

自定义技能同样遵循 SKILL.md 编写规范（详见第三章），只需在 YAML frontmatter 中注明 name、description（Use when... 格式）和 tags，就能被 Claude Code / OpenCode 的被动匹配机制抓取到。

然后在项目的 settings.json 或 opencode.json 中指向你的 fork：

{
  "skills": {
    "paths": ["my-opengis-skills"]
  }
}

这样你既继承了上游 66 个标准技能的持续更新，又有自己的专属扩展。

4.10.4 定期更新

opengis-skills 是一个持续更新的仓库。保持与上游同步可以让你获得：

  • 新工具的技能支持（如新版本的 QGIS、新增的 GDAL 驱动等）
  • 现有技能的 API 更新（上游项目变更后，技能文件会相应修正）
  • 社区贡献的改进（更完善的 FAQ、更多工作流示例、性能优化建议）

更新 submodule：

# 进入 submodule 目录
cd opengis-skills

# 拉取上游最新代码
git fetch origin
git checkout main  # 或你跟踪的分支
git merge origin/main

# 回到主项目，提交 submodule 更新
cd ..
git add opengis-skills
git commit -m "chore: update opengis-skills submodule"

更新频率建议：

场景 更新频率
生产环境项目 每季度一次，在迭代间隙集中更新和验证
个人开发项目 每月一次，有重要新功能时手动触发
学习/探索 随时更新，保持和社区最新进展一致

更新前检查清单：

  1. 查看上游的 commits 记录 了解变更内容
  2. 评估变更对当前项目的影响（是否修改了你正在使用的技能的 API 示例？）
  3. 如果是团队项目，在更新前通知团队成员
  4. 更新后在本地快速验证几个常用技能是否仍然正常工作

4.10.5 多工具混用的协调策略

许多开发者日常会同时使用多个 AI 工具（例如 VS Code 用 Cursor 写前端，终端用 Claude Code 处理后端脚本，再用 DeepSeek Chat 做中文文档翻译）。在这种多工具混用场景中，opengis-skills 的配置文件需要协调一致：

核心原则：在每一份配置文件中写相同（或兼容）的技能路径映射，避免在不同工具中给出矛盾的指令。

示例——为同一个项目配置三种工具：

1. CLAUDE.md / settings.json（Claude Code）：

{
  "skills": {
    "paths": ["opengis-skills"]
  }
}

2. .cursorrules（Cursor）：

# GIS Development
When working with geospatial data, reference:
- @file:opengis-skills/gis/gdal/SKILL.md for GDAL
- @file:opengis-skills/gis/geoserver/SKILL.md for GeoServer

3. .clinerules（Cline）：

# Available Skills
- GDAL command reference: @opengis-skills/gis/gdal/SKILL.md
- GeoServer config reference: @opengis-skills/gis/geoserver/SKILL.md

三份文件都指向同一个 opengis-skills/ 路径，确保无论你用哪个工具，AI 获取的技能信息一致。

4.10.6 新手入门 checklist

如果你是第一次在项目中集成 opengis-skills，按以下步骤操作：

  1. 将 opengis-skills 添加为 Git Submodule：git submodule add https://github.com/znlgis/opengis-skills.git
  2. 根据你使用的工具，创建对应的配置文件（选其一或全部）：
    • Claude Code 用户：.claude/settings.json + CLAUDE.md
    • Cursor 用户：.cursorrules
    • Cline/Roo Code 用户：.clinerules
    • Copilot Chat 用户：.github/copilot-instructions.md
    • OpenCode 用户：opencode.json + AGENTS.md
  3. 用 AI 工具测试基础功能：@opengis-skills/SKILL.md 列出所有与 GDAL 相关的技能
  4. 尝试一个实际任务：@opengis-skills/gis/gdal/SKILL.md 帮我把一个 Shapefile 转换成 GeoJSON
  5. 将配置文件提交到 Git（涉及团队的项目确保 .gitmodules 也被提交）
  6. 通知团队成员安装 submodule：git submodule update --init --recursive

完成这六步后，你和你的团队就拥有了一个可在 AI 工具中随时调用的 GIS/CAD/C#/AI/IoT/3D 知识库。

下一章：第五章：GIS 技能详解 — 深入拆解 23 个 GIS 领域技能的核心 API 和使用场景

↑