ForcePilot/docs/agents/skills-management.md

# Skills 管理系统

Skills 是 Yuxi 系统中用于扩展 Agent 能力的重要机制。通过 Skills，开发者可以将特定的工具、提示词模板或领域知识打包成可复用的技能包，让 Agent 在对话过程中能够调用这些额外能力。

## 为什么需要 Skills

在实际业务场景中，我们常常会遇到一些特定的需求：比如需要 Agent 能够查询特定的 API、调用某个外部服务、或者使用特定的提示词模板来完成特定任务。传统的做法是在代码中硬编码这些功能，但这样会导致系统变得越来越臃肿，且难以复用。

Skills 系统的设计理念就是将这类"可插拔"的能力封装成独立的技能包。每个 Skill 包含完整的实现文件和元数据，Agent 可以根据配置动态加载所需的技能，实现能力的灵活组合。

## 架构设计

Skills 系统采用「文件系统存内容，数据库存索引」的分离架构：

```
┌─────────────────────────────────────────────────────────────┐
│                      Skills 存储架构                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   /app/saves/skills/          数据库索引                    │
│   ├── skill-a/               ┌──────────────┐              │
│   │   ├── SKILL.md           │ skills 表    │              │
│   │   ├── tools/             │ - slug       │              │
│   │   └── prompts/           │ - name       │              │
│   └── skill-b/               │ - description│              │
│       ├── SKILL.md           │ - dir_path   │              │
│       └── ...                │ - deps...    │              │
│                              └──────────────┘              │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### 存储结构

- **文件系统**：`/app/saves/skills` 目录下，每个 Skill 占用一个子目录
- **数据库索引**：`skills` 表存储元数据（slug、name、description、依赖关系等）
- **关联机制**：通过 `dir_path` 字段关联文件系统目录与数据库记录

::: tip 不能直接在文件系统创建
由于 Skills 的元数据需要写入数据库，因此不能直接在文件系统中创建 Skill。必须通过系统的导入功能或在线创建功能来完成，系统会自动处理数据库记录的创建。
:::

## 创建方式

系统提供四种方式创建 Skills：

1. **ZIP 导入（推荐）**：将 Skill 目录打包成 ZIP，通过管理界面上传导入
2. **在线创建**：通过 Skills 管理页面在线创建目录和文件
3. **远程仓库安装**：在 Skills 管理页面填写 skills 仓库地址和 skill 名称，由后端调用 `npx skills` 下载后再导入系统
4. **手动导入**：直接操作数据库（不推荐，需要手动同步文件系统和数据库）

## Skills 来源

Skills 本质上是提示词和工具的封装，以下是一些可以参考的 Skills 实现：

- **Anthropic 官方 Tools**：https://github.com/anthropics/skills 可以参考其 skills 的组织方式和提示词设计
- **MiniMax-AI CLI**：https://github.com/MiniMax-AI/cli 文本、图片、视频、语音和音乐生成 + Web 搜索（可通过 `MiniMax-AI/cli` 远程安装）
- **社区 Skills**：各平台分享的 Agent 提示词模板
- **自定义开发**：根据业务需求自行开发

## 快速开始

### 创建你的第一个 Skill

一个标准的 Skill 目录结构如下：

```
my-awesome-skill/
├── SKILL.md              # 必选，Skill 的核心定义文件
├── tools/                # 可选，相关的工具脚本
│   └── helper.py
└── prompts/              # 可选，提示词模板
    └── system.md
```

其中 `SKILL.md` 是每个 Skill 必须包含的核心文件，它采用 Markdown + Frontmatter 格式：

```markdown
---
name: my-awesome-skill
description: 这是一个用于处理特定任务的技能
---

# Skill 使用说明

这里是技能的详细使用文档，Agent 会读取这部分内容来了解如何使用这个技能。

## 功能列表

1. 功能一：xxx
2. 功能二：yyy

## 使用示例

当用户 xxx 时，可以调用此技能...
```

**Frontmatter 字段说明：**

| 字段 | 必填 | 说明 |
|------|------|------|
| `name` | 是 | Skill 名称，必须是小写字母、数字、短横线的组合（如 `my-skill`） |
| `description` | 是 | Skill 的功能描述，会在 Agent 配置时展示 |

### 导入 Skill

有三种方式可以导入 Skill：

**方式一：通过 ZIP 包导入（推荐）**

1. 将 Skill 目录打包成 ZIP 文件（注意：ZIP 的根目录就是 Skill 目录）
2. 在系统设置的「Skills 管理」页面，点击「导入 Skill」
3. 上传 ZIP 文件即可

系统会自动：
- 校验 ZIP 内容和路径安全性
- 检查 slug 冲突（如有冲突会自动追加 `-v2` 等后缀）
- 解析 SKILL.md 的 frontmatter 并存储到数据库

**方式二：在线创建**

在 Skills 管理页面，你可以：
- 新建目录或文件
- 在线编辑文本文件（支持 .md、.py、.js、.json 等格式）
- 直接在网页上编写 SKILL.md 内容

**方式三：从远程 skills 仓库安装**

1. 在 Skills 管理页面的“远程安装”面板中填写仓库来源，例如 `anthropics/skills` 或完整 GitHub URL
2. 点击“查看可安装 Skills”获取该仓库中可发现的 skills 列表
3. 选择或输入目标 skill 名称后点击“安装”

系统会在后端：
- 调用 `npx skills add <source> --list` 校验来源并发现可安装的 skills
- 使用隔离的临时 `HOME` 执行 `npx skills add <source> --skill <name> -g -y --copy`
- 从临时目录中提取对应 skill，再按现有导入流程写入 `/app/saves/skills` 与数据库

::: tip 远程安装不会把 ~/.agents/skills 作为系统主存储
远程安装只把 `skills.sh` CLI 作为“下载器”使用。Yuxi 仍然以 `/app/saves/skills + skills 表` 作为正式来源，这样才能与现有的权限、线程可见性和沙盒挂载机制保持一致。
:::

## 依赖系统

Skills 之间可以建立依赖关系，形成一个松耦合的技能网络。

### 依赖类型

每个 Skill 可以声明三类依赖：

| 依赖类型 | 说明 | 加载时机 |
|----------|------|----------|
| `tool_dependencies` | 需要的内置工具 | 激活后按需加载 |
| `mcp_dependencies` | 需要的 MCP 服务 | 激活后按需加载 |
| `skill_dependencies` | 依赖的其他 Skill | 会话启动即生效 |

### 渐进式加载机制

系统采用三级渐进式加载策略，确保资源的高效利用：

**阶段一：会话启动**

当 Agent 会话启动时，系统会：
1. 读取 Agent 配置中的 `context.skills` 列表
2. 递归展开 `skill_dependencies`，构建完整的可见技能集（`visible_skills`）
3. 将可见技能列表注入到系统提示词中

这意味着：只要配置了某个 Skill，它的依赖 Skill 就会立即对 Agent 可见。

**阶段二：技能激活**

当 Agent 通过 `read_file` 工具读取 `/skills/<slug>/SKILL.md` 时，视为"激活"该技能。系统会：
1. 验证该技能在可见列表中
2. 将其添加到 `activated_skills` 列表
3. 后续的模型调用会使用激活列表来加载依赖

**阶段三：按需加载**

每次模型调用时，系统会：
1. 检查 `activated_skills` 中的技能
2. 收集这些技能的 `tool_dependencies` 和 `mcp_dependencies`
3. 动态将需要的工具和 MCP 服务添加到可用工具集中

这种设计的好处是：不会在会话开始时加载所有工具，而是根据 Agent 实际使用情况按需加载，既节省资源又保证响应速度。

### 依赖声明示例

假设我们有三个 Skills：

- **base-skill**：基础技能，无依赖
- **advanced-skill**：依赖 `base-skill`
- **pro-skill**：依赖 `advanced-skill`

当在 Agent 配置中只选择 `pro-skill` 时：
1. 启动阶段：`visible_skills` = [`pro-skill`, `advanced-skill`, `base-skill`]（自动展开依赖链）
2. Agent 首次调用任何 skill 时：所有三个 Skill 都可见
3. 当 Agent 读取 `pro-skill/SKILL.md` 时：触发激活，工具和 MCP 依赖被加载

## 权限管理

Skills 管理采用基于角色的权限控制：

| 角色 | 权限 |
|------|------|
| 超级管理员 | 完全控制：导入、导出、编辑、删除、配置依赖 |
| 管理员 | 只读：查看 Skills 列表（用于 Agent 配置） |
| 普通用户 | 无访问权限 |

管理员可以在创建或编辑 Agent 时，从 Skills 列表中选择需要的能力。

## 运行时行为

### Agent 如何使用 Skills

1. **提示词注入**：系统会在 Agent 的系统提示词开头自动插入可用 Skills 的描述
2. **文件访问**：Skills 目录以只读方式挂载到 `/skills/<slug>/...`
3. **工具调用**：当 Agent 需要使用某个 Skill 时，会先读取对应的 SKILL.md 了解使用方法

### 文件操作限制

运行时 `/skills` 路径有以下限制：
- **只读**：Agent 只能读取文件内容
- **禁止写入**：不能创建、修改或删除文件
- **路径安全**：所有路径都经过安全校验，防止目录穿越攻击

::: tip 虚拟文件系统限制
当前 Skills 目录挂载为虚拟文件系统，**不支持 shell 命令执行**。Skill 中的脚本仅作为提示词参考，Agent 无法直接执行这些脚本。如果需要执行特定功能，建议通过 MCP 工具或自定义工具实现。
:::

### 会话隔离

每个 Agent 会话都有独立的 Skills 可见集：
- 不同会话可以配置不同的 Skills
- 同一会话内修改 `context.skills` 会触发快照重建
- 后台修改 Skills 内容后，已有会话不会自动刷新

## 最佳实践

### Skill 命名规范

- 使用小写字母、数字和短横线
- 具有描述性，如 `weather-query`、`sql-reporter`
- 避免过长的名称

### 依赖管理建议

- **保持依赖链简洁**：层级不宜过深，一般 1-2 层为宜
- **避免循环依赖**：系统会检测并阻止循环依赖
- **明确依赖必要性**：只在真正需要共享能力时才建立依赖

### SKILL.md 编写技巧

```markdown
---
name: example-skill
description: 简短描述技能功能
---

# 技能名称

这里是详细的使用说明...

## 何时使用

描述在什么场景下应该使用这个技能...

## 使用方法

1. 第一步...
2. 第二步...

## 示例

```
具体的使用示例...
```
```

## 常见问题

**Q：为什么我配置的 Skill 没有生效？**

A：请检查以下几点：
1. Skill 的 slug 是否正确配置在 Agent 的 `context.skills` 中
2. SKILL.md 是否存在且 frontmatter 格式正确
3. 如果使用了依赖，确保依赖链完整

**Q：如何更新已导入的 Skill？**

A：可以通过以下方式：
1. 导出当前 Skill，修改后重新导入
2. 在 Skills 管理页面在线编辑文件
3. 直接修改文件系统中的内容（需要重启服务使缓存失效）

**Q：Skill 依赖的工具/MCP 不存在怎么办？**

A：系统会在保存依赖配置时进行校验，如果引用的工具或 MCP 不存在，会报错并阻止保存。

---

通过 Skills 机制，Yuxi 为 Agent 提供了一个灵活、可扩展的能力扩展框架。你可以将自己积累的业务知识、工具能力封装成 Skills，让不同的 Agent 复用这些能力，极大地提升了系统的可维护性和复用性。