┌──────────────────────────────────────────────────────────────┐
│                    没有 Skill 文件                            │
│                                                              │
│  用户: "帮我做缓冲区分析"                                     │
│  AI:   "你可以用 ArcGIS 的 Buffer 工具..."  ← 不了解框架     │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                    有 Skill 文件                              │
│                                                              │
│  用户: "帮我做缓冲区分析"                                     │
│  AI:   生成正确的 YAML 流水线:                                │
│        steps:                                                │
│          - id: load_data                                     │
│            use: io.read_vector                               │
│            params:                                           │
│              file: ${var.input_file}                         │
│          - id: buffer                                        │
│            use: vector.buffer                                │
│            params:                                           │
│              input: $load_data                               │
│              distance: ${var.buffer_distance}                │
└──────────────────────────────────────────────────────────────┘

skills/geopipe-agent/
├── SKILL.md                          # 主 Skill 描述文件
└── reference/
    ├── steps-reference.md            # 步骤参考文档
    └── pipeline-schema.md            # YAML Schema 文档

#### 错误处理策略

```markdown
### 错误处理

```yaml
steps:
  - id: risky_step
    use: vector.overlay
    on_error: skip    # 可选值: fail (默认), skip, retry
    params:
      ...

### 17.4.3 引用语法详解

Schema 文档中会详细说明三种引用语法：

| 语法 | 含义 | 示例 |
|------|------|------|
| `${var.name}` | 引用变量值 | `${var.buffer_distance}` |
| `$step_id` | 引用步骤的主输出 | `$load_data` |
| `$step_id.stats.key` | 引用步骤的统计信息 | `$qc_check.stats.pass_rate` |

---

## 17.5 generate_skill_file() —— 主 Skill 文件

### 17.5.1 功能说明

`generate_skill_file()` 生成主 SKILL.md 文件，这是 AI 首先阅读的文件，包含框架的整体能力描述和常见使用模式。

### 17.5.2 SKILL.md 结构

生成的 SKILL.md 包含以下核心部分：

```markdown
# GeoPipeAgent Skill

## Overview
GeoPipeAgent 是一个 AI-Native 的 GIS 数据分析流水线框架...

## Quick Start
一个最简单的流水线示例...

## Step Categories
步骤按类别分为: io, vector, raster, spatial, network, qc...

## Common Patterns
### ETL 模式
读取 → 处理 → 保存

### QC 模式
读取 → 多项质检 → 条件保存

### Analysis 模式
读取多层 → 空间分析 → 保存结果

## Reference
- [Steps Reference](reference/steps-reference.md)
- [Pipeline Schema](reference/pipeline-schema.md)

✓ 写入 SKILL.md (12,345 bytes)
✓ 写入 reference/steps-reference.md (28,901 bytes)
✓ 写入 reference/pipeline-schema.md (8,567 bytes)

Skill 文件已生成到: skills/geopipe-agent/

┌─────────────────────────────────────────────────────────────┐
│  Step 1: 生成 Skill 文件                                     │
│  $ geopipe-agent generate-skill                              │
│                                                              │
│  Step 2: 将 Skill 文件提供给 AI                              │
│  (粘贴 SKILL.md 内容到 AI 对话中)                            │
│                                                              │
│  Step 3: 用自然语言描述需求                                   │
│  "帮我分析北京市的道路数据,做500米缓冲区并保存为GeoPackage"    │
│                                                              │
│  Step 4: AI 生成 YAML 流水线                                 │
│  (AI 根据 Skill 知识生成正确的 YAML)                         │
│                                                              │
│  Step 5: 校验并执行                                          │
│  $ geopipe-agent validate pipeline.yaml                      │
│  $ geopipe-agent run pipeline.yaml                           │
│                                                              │
│  Step 6: AI 解读结果                                         │
│  (将执行结果反馈给 AI,获取分析建议)                          │
└─────────────────────────────────────────────────────────────┘

我有一份北京市的道路数据（roads.shp，坐标系 EPSG:4326），需要：
1. 转换到 EPSG:3857 投影坐标系
2. 对主干道（road_type = 'primary'）做 500 米缓冲区
3. 保存为 GeoPackage 格式

执行结果:
{
  "status": "success",
  "steps_completed": 5,
  "outputs": {
    "load_roads": {"rows": 12345, "crs": "EPSG:4326"},
    "filter_primary": {"rows": 2341},
    "buffer": {"rows": 2341, "crs": "EPSG:3857"},
    "save": {"file": "output/primary_road_buffer.gpkg"}
  }
}

你是一个 GIS 分析专家，使用 GeoPipeAgent 框架帮助用户创建数据分析流水线。
请根据上传的 Skill 文件生成正确的 YAML 流水线。
始终使用 vars 定义可配置参数。
在分析结果中给出专业的 GIS 建议。

请阅读以下 GeoPipeAgent Skill 描述：

[粘贴 SKILL.md 内容]

基于以上信息，帮我创建一个...

<skill>
[SKILL.md 内容]
</skill>

<reference>
[steps-reference.md 内容]
</reference>

<schema>
[pipeline-schema.md 内容]
</schema>

请基于以上 GeoPipeAgent 技能描述，帮我创建一个矢量数据质检流水线。
数据文件：buildings.gpkg
需要检查：几何有效性、拓扑关系、属性完整性。

my-gis-project/
├── skills/
│   └── geopipe-agent/
│       ├── SKILL.md
│       └── reference/
│           ├── steps-reference.md
│           └── pipeline-schema.md
├── pipelines/
│   ├── analysis.yaml
│   └── qc.yaml
└── data/

@workspace 参考 skills/geopipe-agent/SKILL.md，帮我创建一个栅格处理流水线