技能系统
技能（Skill）是 Snail AI 平台中为智能体扩展结构化处理能力的模块。每个技能本质上是一个可上传的 ZIP 包，内部包含一个核心的 SKILL.md 文件以及若干辅助文件（如代码脚本、配置文件、数据文件等）。智能体在运行时会根据绑定的技能，将 SKILL.md 中的指令注入到上下文中，从而赋予智能体特定领域的能力。
核心概念
什么是技能？
技能是一种可复用、可分发的 AI 指令包。与系统提示词（System Prompt）不同，技能以独立的文件包形式存在，具备以下特征：
- 独立封装：每个技能独立打包为 ZIP 文件，包含
SKILL.md主文件和所需的辅助资源文件。 - 声明式元数据：通过
SKILL.md的 YAML frontmatter 声明技能名称、描述等元信息。 - 可组合绑定：一个智能体可以同时绑定多个技能，技能之间互不干扰。
- 在线可编辑：上传后可通过内置的在线文件编辑器直接修改技能内容，无需重新打包上传。
技能与其他能力模块的区别
| 特性 | 技能（Skill） | 系统提示词 | MCP 工具 | RAG 知识库 |
|---|---|---|---|---|
| 存在形式 | 独立文件包（ZIP） | 文本字段 | 远程/本地服务 | 文档 + 向量 |
| 编辑方式 | 在线文件编辑器 | 表单输入 | 服务端配置 | 文档管理 |
| 能力类型 | 结构化指令/流程/规范 | 通用角色设定 | 外部工具调用 | 基于文档的问答 |
| 可分发性 | ZIP 下载/上传 | 不可独立分发 | 需部署服务 | 需导入文档 |
技能生命周期
一个技能从创建到被智能体使用，经历以下完整流程：
创建/上传 → 解析元数据 → 绑定到智能体 → 运行时注入上下文1. 创建/上传
技能支持两种创建方式：
- 在线创建：通过管理界面直接创建技能（仅在数据库中创建记录），随后通过在线编辑器编写
SKILL.md和辅助文件。 - ZIP 上传：将本地制作好的 ZIP 包（必须包含
SKILL.md）上传到平台，系统自动解析 frontmatter 中的元数据。
详细操作请参见 创建技能。
2. 解析元数据
上传后，系统从 SKILL.md 的 YAML frontmatter 中提取技能的名称（name）和描述（description），作为技能在平台中展示的元信息。如果 frontmatter 中未指定，则以文件名或上传时填写的信息为准。
3. 绑定到智能体
在智能体的配置页面中，启用"技能"开关后，即可从已有的技能列表中选择一个或多个技能进行绑定。绑定关系存储在智能体配置中（skillIds 字段）。
4. 运行时解析
当用户与绑定了技能的智能体对话时，Snail AI 的 Agent 责任链会在构建上下文阶段，将绑定技能的 SKILL.md 内容注入到对话上下文中。智能体根据技能指令进行结构化的回答或处理。
技能包结构
一个标准的技能 ZIP 包结构如下：
my-skill.zip
├── SKILL.md # 必须：技能主文件，包含 frontmatter 和指令内容
├── examples/ # 可选：示例文件目录
│ ├── example-1.json
│ └── example-2.md
├── templates/ # 可选：模板文件目录
│ └── report.md
└── config.yaml # 可选：辅助配置文件关键规则
SKILL.md是唯一必须存在的文件，缺少此文件的 ZIP 包将无法上传。SKILL.md不可通过在线编辑器删除（可以编辑内容）。- 辅助文件的组织方式不做限制，可根据技能的具体需求自由安排目录结构。
SKILL.md 格式
SKILL.md 采用 Markdown 格式，顶部使用 YAML frontmatter 声明元数据：
markdown
---
name: 代码审查助手
description: 按照企业编码规范对提交的代码进行审查，输出结构化的审查报告
---
# 代码审查助手
## 审查流程
1. 分析代码结构和命名规范
2. 检查潜在的安全风险
3. 评估代码可读性和维护性
4. 生成结构化审查报告
## 输出格式
审查报告应包含以下部分：
- **总体评分**：1-10 分
- **问题列表**：按严重程度排序
- **改进建议**：具体可操作的改进方案frontmatter 字段说明
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 推荐 | 技能名称，用于平台展示 |
description | string | 推荐 | 技能描述，帮助管理员理解技能用途 |
技能列表页功能
技能列表页以卡片网格形式展示所有已创建的技能，提供以下操作：
- 搜索：按名称或描述关键词搜索技能。
- 在线创建：点击「在线创建」按钮，填写名称和描述后创建新技能。
- 上传 ZIP：点击「上传 ZIP」按钮，选择本地 ZIP 文件上传。
- 编辑：点击卡片上的「编辑」按钮，进入在线文件编辑器。
- 信息：修改技能的名称和描述等元信息。
- 下载：将技能导出为 ZIP 文件下载到本地。
- 删除：删除技能及其所有关联文件。
- 分页：支持设定每页显示数量（10/20/50）和快速跳转。
每张技能卡片展示以下信息：
- 技能图标
- 技能名称
- 技能描述（最多两行）
- 文件名、文件大小、创建时间
使用建议
- 明确技能边界：每个技能应聚焦于一个具体的领域或任务类型，避免将过多不相关的指令混入同一个技能。
- 善用辅助文件：将示例、模板、配置等资源放入辅助文件中，保持
SKILL.md的指令清晰简洁。 - 版本管理：利用下载功能定期备份重要技能的 ZIP 包，便于版本追溯和团队共享。
- 组合使用：为智能体绑定多个互补的技能，例如同时绑定"代码审查"和"文档生成"技能。