---
name: create-skill
description: 帮助用户创建有效的自定义技能，通过具体用例收集需求并生成 SKILL.md
trigger: 用户要求创建技能、新建 skill、帮我写一个技能、我想有个技能能帮我做 X、怎么创建技能
---

# 创建自定义技能

本技能帮助用户创建有效的自定义技能。

## 关于技能

技能是模块化的指令包，通过提供专业化的操作流程、工具调用指令和领域知识，将通用 AI 转变为特定任务的专家。技能就像特定领域的"入职指南"——将程序性知识注入 AI，使其具备模型本身无法完全掌握的实操能力。

### 技能提供什么

1. **专业工作流** — 特定领域的多步骤操作规程
2. **工具集成** — 指示 AI 调用系统 API 或 MCP 工具
3. **领域知识** — 业务逻辑、配置规则、排查经验
4. **配套资源** — 脚本、参考文档和模板

### 技能目录结构

每个技能由必需的 SKILL.md 文件和可选的配套资源组成：

```
skill-name/
├── SKILL.md          ← 必需
│   ├── YAML 元数据（必需）
│   │   ├── name:（必需）
│   │   ├── description:（必需）
│   │   └── trigger:（可选）
│   └── Markdown 指令内容（必需）
└── 配套资源（可选）
    ├── scripts/          — 可执行脚本（Python/Bash 等）
    ├── references/       — 按需加载的参考文档
    └── assets/           — 输出中使用的文件（模板、图标等）
```

#### SKILL.md（必需）

**元数据质量**：`name` 和 `description` 决定了 AI 何时使用该技能。描述要具体说明技能做什么、何时使用。使用第三人称（如"该技能用于..."）。

**触发条件**：`trigger` 用自然语言描述技能的适用场景，帮助 AI 判断用户请求是否匹配。多个条件用中文逗号分隔，覆盖用户可能的不同说法，但不要过于宽泛。

#### 配套资源（可选）

##### 脚本 (`scripts/`)

需要确定性执行或反复重写的可执行代码。

- **适用场景**：相同代码每次都要重写、需要确定性结果的任务
- **示例**：`scripts/export_csv.py` 数据导出脚本
- **优势**：省 token、结果确定、可直接执行无需读入上下文

##### 参考资料 (`references/`)

AI 在执行过程中按需读取的文档。

- **适用场景**：数据库 Schema、API 文档、领域知识、公司政策
- **示例**：`references/api_docs.md` API 规格文档
- **最佳实践**：大文件（>5000 字）在 SKILL.md 中提供 grep 搜索模式，让 AI 精准定位而非全量读取
- **避免重复**：信息只放在 SKILL.md 或 references 中一处，不要两处都有。核心操作指令放 SKILL.md，详细参考资料放 references

##### 输出资源 (`assets/`)

不需要读入上下文、只在输出中使用的文件。

- **适用场景**：模板、图片、样板代码、字体
- **示例**：`assets/report_template.md` 报告模板
- **优势**：将输出资源与文档分离，AI 无需加载即可使用

### 渐进加载设计

技能采用三级加载机制，按需占用上下文：

| 层级 | 内容 | 何时加载 | 大小 |
|------|------|----------|------|
| **第一层** | 元数据（名称 + 描述 + 触发条件） | 始终在系统提示词中 | ~100 字 |
| **第二层** | SKILL.md 正文（指令内容） | 技能触发时 | <5000 字 |
| **第三层** | 配套资源（脚本、参考文档） | AI 按需读取 | 不限 |

脚本可以直接执行而无需读入上下文，因此第三层不受限制。

## 技能分类

| 分类 | 存放位置 | 说明 |
|------|----------|------|
| **系统** | `skills/system/` | 内置技能，不可删除和编辑 |
| **预设** | `skills/preset/` | 预装技能，可删除但不可编辑 |
| **用户** | `~/.protocol-proxy/skills/` | 用户自定义技能，可自由编辑和删除 |

通过智控助手面板创建的技能属于**用户**分类。

## 创建流程

要创建一个技能，按顺序执行以下步骤，除非有明确理由跳过某步。

### 第一步：通过具体用例理解技能

仅当技能的使用场景已经非常清晰时才跳过此步。即使在迭代已有技能时，此步仍有价值。

要创建有效的技能，需要清楚理解技能将如何被使用的**具体用例**。这些用例可以来自用户的直接描述，也可以由 AI 生成后由用户验证。

例如，创建一个"日志分析"技能时，相关问题包括：

- "这个技能主要分析哪类日志？错误日志、请求日志、还是都包括？"
- "能举几个你会怎么使用这个技能的例子吗？"
- "我能想到用户会说'最近有什么报错'或者'帮我分析一下日志趋势'。你还能想到其他说法吗？"
- "什么情况下用户说的话应该触发这个技能？"

为避免让用户应接不暇，不要一次问太多问题。先问最重要的，按需追问。

当对技能要支持的功能有了清晰认知时，结束此步。

### 第二步：规划可复用的技能内容

要将具体用例转化为有效的技能，对每个用例进行分析：

1. 从零开始执行这个用例需要哪些步骤
2. 重复执行这些工作流时，哪些脚本、参考文档和模板会有帮助

示例：创建 `pdf-editor` 技能处理"帮我旋转这个 PDF"：
1. 旋转 PDF 每次都要重写相同的代码
2. 在 `scripts/rotate_pdf.py` 中存储旋转脚本会有帮助

示例：创建 `frontend-webapp-builder` 技能处理"帮我建个 todo 应用"：
1. 写前端应用每次都需要相同的样板代码
2. 在 `assets/hello-world/` 中存储样板项目会有帮助

示例：创建 `big-query` 技能处理"今天有多少用户登录"：
1. 查询 BigQuery 每次都要重新发现表结构和关系
2. 在 `references/schema.md` 中记录表结构会有帮助

通过分析每个用例，确定要包含的可复用资源清单：脚本、参考文档和模板。

### 第三步：创建技能

此时开始实际创建技能。

如果是新建技能，在智控助手中通过技能面板创建：

1. 点击输入框右侧「⚡」按钮打开技能面板
2. 点击「+」按钮创建新技能
3. 填写名称、描述、触发条件和指令内容
4. 点击「保存」

创建后可在技能面板中点击技能名称进行编辑。通过面板创建的技能属于**用户**分类。

如果需要包含配套资源（scripts/references/assets），需要手动在 `~/.protocol-proxy/skills/<skill-name>/` 目录下创建对应子目录和文件。

### 第四步：编辑技能

编辑技能时，记住这个技能是为**另一个 AI 实例**使用的。重点包含对 AI 有益且非显而易见的信息。考虑哪些程序性知识、领域细节或可复用资源能帮助另一个 AI 实例更有效地执行任务。

#### 先处理配套资源

从第一步规划的可复用资源开始：`scripts/`、`references/` 和 `assets/` 文件。注意这一步可能需要用户提供输入。例如，创建 `brand-guidelines` 技能时，用户可能需要提供品牌素材存到 `assets/`，或文档存到 `references/`。

同时，删除技能中不需要的示例文件和目录。

#### 更新 SKILL.md

**写作风格**：整个技能使用**祈使语气**（动词开头的指令），不用第二人称。使用客观的指令式语言（如"要完成 X，执行 Y"而不是"你应该做 X"或"如果需要 X 的话"）。这保证了 AI 消费时的一致性和清晰度。

要完成 SKILL.md，回答以下问题：

1. 技能的目的是什么？用几句话概括。
2. 何时应该使用这个技能？
3. 实际使用中，AI 应该如何使用这个技能？上面开发的所有可复用资源都应被引用，让 AI 知道如何使用它们。

## 可用工具参考

在技能中可以指示 AI 调用以下工具。MCP 工具也可以在技能中引用，AI 会自动调用。

### 系统查询（只读）

| 工具 | 用途 |
|------|------|
| `get_system_status` | 获取系统状态概览 |
| `check_health` | 系统健康检查 |
| `get_providers` | 获取所有供应商 |
| `get_provider` | 获取单个供应商详情 |
| `get_proxies` | 获取所有代理 |
| `get_proxy` | 获取单个代理详情 |
| `get_key_health` | 获取密钥健康状态 |
| `get_usage_stats` | 获取用量统计 |
| `get_recent_requests` | 获取最近请求日志（支持按代理/状态/模型过滤） |
| `get_system_logs` | 获取系统日志 |
| `get_settings` | 获取系统设置 |
| `get_config_history` | 获取配置版本历史 |
| `test_provider_keys` | 测试供应商密钥连通性 |
| `get_provider_models` | 获取供应商可用模型列表 |

### 文件操作

| 工具 | 用途 | 权限 |
|------|------|------|
| `read_file` | 读取文件内容 | 只读 |
| `list_directory` | 列出目录内容 | 只读 |
| `search_files` | 按 glob 模式搜索文件 | 只读 |
| `grep_search` | 按正则搜索文件内容 | 只读 |
| `write_file` | 写入文件 | 需审批 |
| `edit_file` | 精确替换文件内容 | 需审批 |
| `execute_command` | 执行系统命令 | 需审批 |

### 供应商管理

| 工具 | 用途 |
|------|------|
| `create_provider` | 创建供应商 |
| `update_provider` | 更新供应商配置 |
| `delete_provider` | 删除供应商 |

### 代理管理

| 工具 | 用途 |
|------|------|
| `create_proxy` | 创建并启动代理 |
| `update_proxy` | 更新代理配置 |
| `delete_proxy` | 删除代理 |
| `start_proxy` | 启动代理 |
| `stop_proxy` | 停止代理 |
| `start_all_proxies` | 启动所有代理 |
| `stop_all_proxies` | 停止所有代理 |

### MCP 服务管理

| 工具 | 用途 |
|------|------|
| `get_mcp_servers` | 列出 MCP 服务及状态 |
| `add_mcp_server` | 添加 MCP 服务 |
| `update_mcp_server` | 更新 MCP 服务 |
| `delete_mcp_server` | 删除 MCP 服务 |
| `connect_mcp_server` | 连接 MCP 服务 |
| `disconnect_mcp_server` | 断开 MCP 服务 |
| `get_mcp_tools` | 列出已连接 MCP 服务的工具 |

### 技能管理

| 工具 | 用途 |
|------|------|
| `get_skills` | 列出所有技能 |
| `create_skill` | 创建新技能 |
| `update_skill` | 更新技能 |
| `delete_skill` | 删除技能 |
| `invoke_skill` | 调用技能获取指令 |

### 记忆系统

| 工具 | 用途 |
|------|------|
| `get_memory` | 查看所有记忆（含人设） |
| `save_memory` | 保存记忆条目 |
| `read_memory` | 读取二级记忆条目详情 |
| `edit_memory` | 编辑或删除记忆条目 |
| `search_memory` | 按关键词搜索记忆条目 |
| `update_soul` | 更新智能体人设（SOUL.md） |

### 配置管理

| 工具 | 用途 |
|------|------|
| `export_config` | 导出系统配置 |
| `import_config` | 导入配置（合并/覆盖） |
| `rollback_config` | 回滚到历史配置版本 |
| `reconstruct_config` | 通过回溯差异链重建指定配置版本 |
| `get_config_diff` | 比较两个配置版本之间的差异 |
| `update_settings` | 更新系统设置 |
| `trigger_key_health_check` | 手动触发密钥健康检查 |

### 多智能体委派

| 工具 | 用途 |
|------|------|
| `delegate_task` | 委派子任务给子代理并行执行 |
| `list_agents` | 列出所有可用的代理身份 |
| `list_tasks` | 列出子任务（可按状态筛选） |
| `get_task` | 获取子任务详情 |
| `stop_task` | 终止运行中的子任务 |
| `message_task` | 向已完成或失败的子任务追加消息 |

### 会话管理

| 工具 | 用途 |
|------|------|
| `list_conversations` | 列出所有历史会话 |
| `delete_conversation` | 删除指定会话 |
| `clear_conversation` | 清空会话消息历史 |

### 执行策略

| 工具 | 用途 |
|------|------|
| `get_exec_policy` | 获取当前执行策略概览 |
| `test_exec_policy` | 测试命令在当前策略下的决策结果 |

### 第五步：验证技能

技能创建完成后，需要验证其是否按预期工作：

1. **手动触发**：输入 `/技能名`，检查 AI 是否按指令执行、输出是否符合模板
2. **自动触发**：用自然语言提问（不带 `/`），测试触发条件是否精准匹配
3. **边界测试**：用模糊或略有偏差的问题测试，确认不会误触发

如果验证失败，回到第四步修改 SKILL.md，然后再次验证。

### 第六步：迭代优化

用户测试技能后可能会要求改进。通常这发生在刚使用完技能之后，此时对技能的表现有最新鲜的感受。

**迭代流程**：
1. 用技能处理实际任务
2. 观察 AI 在哪里卡住或输出不符预期
3. 确定 SKILL.md 或配套资源需要如何更新
4. 实施修改并再次测试
