# 案例三：创建技能

## 场景说明

技能（Skill）是扩展智能体能力的模块化组件。当你发现智能体缺少某个专业能力时，可以为它创建一个技能。比如：自动生成 PPT、调用特定 API、处理特定格式的文件等。

## 前置准备

- 已完成 [安装](../getting-started/installation.md)
- 了解技能的基本概念
- 知道你想让智能体学会什么新能力

## 操作步骤

### 步骤 1：理解技能结构

一个技能是一个文件夹，包含以下结构：

```
my-skill/
├── SKILL.md          # 技能主文件（必需）
├── scripts/          # 可执行脚本（可选）
├── references/       # 参考资料（可选）
└── assets/           # 模板、图标等资源（可选）
```

其中 `SKILL.md` 是最核心的文件，包含 YAML 元信息和技能描述。

<!-- 截图占位：create-skill-step1.png — 技能结构示意 -->

> **截图说明**：展示技能文件夹的目录结构截图。

### 步骤 2：进入技能管理

在 EvoPanel 左侧导航栏中，点击 **「技能」** 图标，进入技能管理页面。

<!-- 截图占位：create-skill-step2.png — 进入技能管理 -->

> **截图说明**：展示左侧导航栏，标注"技能"图标位置。

### 步骤 3：点击创建新技能

在技能管理页面，点击 **「+ 新建技能」** 按钮。

<!-- 截图占位：create-skill-step3.png — 点击新建技能 -->

> **截图说明**：展示技能管理页面，标注"新建技能"按钮。

### 步骤 4：填写技能信息

填写以下信息：

- **名称**：技能的英文名称（如 `report-generator`）
- **描述**：用一句话描述这个技能做什么，以及何时触发。**这是最重要的部分**，智能体根据描述判断何时调用这个技能。

**示例描述：**

```
当用户需要将数据、分析结果或文本内容生成格式化报告时使用此技能。
支持 Markdown、HTML 和纯文本格式输出。
```

<!-- 截图占位：create-skill-step4.png — 填写技能信息 -->

> **截图说明**：展示技能信息填写表单，标注名称和描述输入框。

### 步骤 5：编写 SKILL.md 正文

SKILL.md 正文部分用自然语言描述：

- 技能的工作流程
- 输入要求
- 输出格式
- 注意事项和边界条件

**示例正文：**

```markdown
## 工作流程

1. 确认用户需要的报告类型（日报/周报/分析报告）
2. 收集或确认数据源
3. 按照模板生成报告
4. 输出给用户确认

## 输出格式

报告应包含：
- 标题和日期
- 核心指标摘要
- 详细数据（表格或图表）
- 结论和建议
```

<!-- 截图占位：create-skill-step5.png — 编写 SKILL.md -->

> **截图说明**：展示 SKILL.md 编辑器界面，标注正文内容区域。

### 步骤 6：添加脚本和参考（可选）

如果你的技能需要执行代码（如调用 API、处理文件），在 `scripts/` 目录下添加脚本文件。如果有模板或参考文档，放在 `assets/` 和 `references/` 目录下。

### 步骤 7：保存并测试

点击 **「保存」**，然后在对话中测试技能是否被正确触发。

**测试提示词：**

```
请帮我生成一份本周的数据分析报告。
```

如果智能体正确识别并调用了你的技能，说明创建成功。

<!-- 截图占位：create-skill-step7.png — 测试技能 -->

> **截图说明**：展示对话中技能被触发和执行的界面。

## 小结

技能创建完成后，会自动加载到智能体的能力库中。描述写得越精准，智能体越能在合适的时机调用它。你可以随时修改和更新技能内容。

<!-- ACCEPTANCE_RECORD_BEGIN -->

# 《案例三：创建技能》流式验收报告

| 元数据项 | 填写 |
|----------|------|
| **报告 ID** | `20260512-084542-case3-v1` |
| **关联案例 / 场景** | [案例三：创建技能](create-skill.md) |
| **关联仓库文档** | 本页正文上方「案例」章节 |
| **执行人** | 自动化 `case_doc_acceptance_append.py` |
| **执行时间（本地）** | `2026-05-12T08:45:59.184434+00:00` |
| **代码版本** | `a877c3b3` |
| **Gateway 基址** | `http://127.0.0.1:8070` |
| **LangGraph 端口（若已知）** | 2070（由 Gateway 代理） |
| **session_key** | `agent:main:case-doc-20260512-084542` |
| **默认 assistant_id** | `lead_agent` |

---

## 1. 测试范围与通过准则

**本报告覆盖：**与本案例文档对应的流式/API 验收（共 **1** 次用户发起）。

**功能通过准则：**以本案例文档操作步骤中「可经流式接口验证」的子目标为准；无未处理 SSE error；主答复可读。

**性能与可观测性准则：**记录 `request_total_ms`、TTFT（`first_ai_visible_ms`）及侧载耗时，供与历史 JSON 对比。

---

## 2. 环境与前置条件

| 检查项 | 状态（是/否/不适用） | 说明 |
|--------|----------------------|------|
| 模型与 API Key | 是 | 以本机已配置为准 |
| 技能 / MCP / 渠道 | 未逐项核对 | 见案例前置说明 |
| 沙箱与写盘范围 | 未逐项核对 | 见网关配置 |
| 与本场景相关的配置项 | 未逐项核对 |  |

**原始机器产物：** `docs/cases/reports/raw/case-doc-3-20260512-084542.json`

---

## 3. 交互总览

| 指标 | 值 |
|------|-----|
| **用户发起流式交互总次数** | 1 |
| **涉及 thread_id 数量** | 1 |
| **是否出现 SSE error / HTTP 非 2xx** | 否 |
| **工具调用总次数（含重复 tool_call_id 刷新）** | 2 |

**thread 与时间线：**

| 序号 | thread_id | 用途说明 |
|------|-----------|----------|
| 1 | `8d0de212-d05e-4a49-be87-d8c5dcc1b164` | 见下节分轮 |

---

## 4. 分轮交互记录

### 4.1 轮次 1

#### 4.1.1 请求与用户输入

| 字段 | 内容 |
|------|------|
| **thread_id** | `8d0de212-d05e-4a49-be87-d8c5dcc1b164` |
| **本轮在用户界面的序号** | 1 / 1 |
| **activated_scenarios** | `["manage"]` |
| **collab_phase** | `idle` |
| **is_plan_mode / subagent_enabled / thinking_enabled** | `False` / `False` / `False` |
| **recursion_limit** | `240` |
| **用户输入（原文，完整）** | `（见 `e2e_scenarios_api_test.run_scenario_create_skill` 内 `prompt` 全文）` |

#### 4.1.2 流式与模型侧时序（本轮）

| 指标 | 值（ms） | 说明 |
|------|----------|------|
| **request_total_ms** | 15954.559 | 自 POST 起至流读完 |
| **first_sse_payload_ms** | 1007.584 | 至首条有效 data: |
| **first_ai_visible_ms（TTFT）** | 14361.189 | 至首段可见助手正文 |
| **assistant_visible_stream_ms** | 37.903 | 首末次可见正文时间差 |
| **本轮是否出现 error 事件** | 否 |  |

#### 4.1.3 工具调用明细（本轮，按发生顺序）

| # | tool 名称 | tool_call_id | duration_ms | 结果摘要 | 备注 |
|---|-----------|----------------|-------------|----------|------|
| 1 | scenario | `functions.scenario:0` | 1200.775 | 成功 |  |
| 2 | skill_manager | `functions.skill_manager:1` | 2265.331 | 成功 |  |

#### 4.1.4 模型输出（本轮）

- [x] **正文粘贴**（完整或截断说明见上）

```text
技能已成功创建：

- **名称**: e2e-skill-bootstrap-20260512164543
- **路径**: `D:\github\EvoFlow\skills\custom\e2e-skill-bootstrap-20260512164543`
- **SKILL.md**: `D:\github\EvoFlow\skills\custom\e2e-skill-bootstrap-20260512164543\SKILL.md`

技能已就绪，可用于自动化验收测试。如需后续清理，可手动删除该技能目录。
```

#### 4.1.5 本轮结论（非总评）

| 项 | 内容 |
|----|------|
| **对照准则条目** | 案例三：技能落盘与可见回复 |
| **子目标是否达成** | 符合 |
| **证据** | `ai_text_seen=True`；侧载种类数 `2` |

---

## 5. 测试意见（文档末尾总评）

### 5.1 结论摘要

- **总体结果：**通过
- **阻塞项：**无
- **非阻塞问题：**无


### 5.2 风险与影响

无额外结论；以本案例业务风险为准。

### 5.3 后续建议

若发布前 gate：可对比 `docs/cases/reports/raw` 中历史 JSON 做基线回归。

<!-- ACCEPTANCE_RECORD_END -->
