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   │              │
│       └── ...                │ - source_type│              │
│                              │ - share_config              │
│                              │ - enabled     │              │
│                              │ - deps...     │              │
│                              └──────────────┘              │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### 存储结构

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

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

## 创建方式

系统提供以下方式创建或安装 Skills：

1. **推荐 Skill 安装**：在 Skills 管理页的推荐分组点击 `+`，系统会拉取对应远程来源并生成安装草稿
2. **ZIP / SKILL.md 上传**：上传后先解析为安装草稿，确认共享范围后再写入正式 Skills 存储和数据库
3. **远程仓库安装**：填写 skills 仓库地址、ModelScope Skill 地址或合集地址，后端调用 `npx skills` 下载并解析为安装草稿，确认后导入系统
4. **在线编辑**：对已有且可管理的 Skill 在线创建目录、编辑文件和维护依赖
5. **Agent 内安装**：主智能体可通过 `install_skill` 工具，从沙盒路径或 Git 来源安装当前用户私有 Skill；子智能体禁用该工具

不建议直接操作数据库或文件系统导入 Skill。直接写文件不会自动生成 `skills` 表记录，也无法参与权限、依赖和沙盒挂载。

## Skills 来源

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

- **Anthropic 官方 Tools**：https://github.com/anthropics/skills 可以参考其 skills 的组织方式和提示词设计
- **ModelScope Skill 市场**：https://modelscope.cn/skills 支持单个 Skill 地址，也支持合集地址批量拉取
- **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
slug: my-awesome-skill
description: 这是一个用于处理特定任务的技能
---

# Skill 使用说明

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

## 功能列表

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

## 使用示例

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

**Frontmatter 字段说明：**

| 字段 | 必填 | 说明 |
|------|------|------|
| `name` | 是 | Skill 展示名称，可使用更易读的名称（如 `Word / DOCX`） |
| `slug` | 否 | Skill 唯一标识，必须是小写字母、数字、短横线的组合，且不能连续短横线（如 `my-skill`）。未填写时兼容旧格式，系统会使用 `name` 作为 slug，此时 `name` 也必须满足 slug 规则 |
| `description` | 是 | Skill 的功能描述，会在 Agent 配置时展示 |

### 导入 Skill

可以通过以下方式导入或安装 Skill：

**方式一：从推荐列表安装**

1. 在系统设置的「Skills 管理」页面查看「推荐」分组
2. 未安装的推荐 Skill 会以普通 Skill 卡片样式展示，右侧显示 `+`
3. 点击推荐卡片或 `+` 后，系统会使用该 Skill 的远程来源拉取内容
4. 拉取成功后会弹出安装草稿，确认共享范围后完成安装

已安装的推荐 Skill 不会继续显示在「推荐」分组中。

**方式二：通过 ZIP 包或 SKILL.md 上传**

1. 将 Skill 目录打包成 ZIP 文件（注意：ZIP 的根目录就是 Skill 目录）
2. 在系统设置的「Skills 管理」页面，点击「上传 Skill」
3. 上传 ZIP 文件或单个 `SKILL.md`
4. 系统解析上传内容并返回安装草稿
5. 确认共享范围后完成安装；也可以放弃草稿

系统会自动：
- 校验 ZIP 内容和路径安全性
- 检查 slug 冲突（如有冲突会自动追加 `-v2` 等后缀）
- 解析 SKILL.md 的 frontmatter 并存储到数据库
- 按当前用户角色校验可选择的共享范围

**方式三：从远程来源安装**

1. 在 Skills 管理页面点击「远程安装」
2. 在“按仓库拉取”中填写来源，例如：
   - `anthropics/skills`
   - `https://github.com/anthropics/skills`
   - `https://modelscope.cn/skills/@anthropics/pdf`
   - `https://modelscope.cn/collections/MiniMax/MiniMax-Office-skills`
3. 点击“拉取技能”获取该来源中可发现的 Skills 列表
4. 单个 Skill 地址通常会自动选中；仓库或合集地址可在列表中勾选一个或多个 Skills
5. 点击“解析并确认”，系统返回安装草稿，确认共享范围后正式安装

也可以切换到“全局搜索发现”，输入关键字检索 skills.sh 上的开源 Skills，再选择结果安装。

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

::: tip ModelScope 合集适合批量安装
ModelScope 合集地址可以作为远程来源填写，例如 `https://modelscope.cn/collections/MiniMax/MiniMax-Office-skills`。拉取后在列表中勾选需要的 Skills，再统一解析为安装草稿。
:::

**方式四：在线编辑已有 Skill**

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

只有具备 `can_manage` 权限的用户才能编辑文件、依赖、共享范围和启用状态。

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

## 依赖系统

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

### 依赖类型

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

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

### 渐进式加载机制

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

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

当 Agent 会话启动时，系统会：
1. 在创建 Graph 前读取已过滤的 `context.skills` 列表
2. 递归展开 `skill_dependencies`，派生 `_prompt_skills` 和 `_readable_skills`
3. 将 `_prompt_skills` 对应的技能说明注入到系统提示词中

这意味着：只要配置了某个 Skill，它的依赖 Skill 就会立即进入提示词和沙盒 `/home/gem/skills` 只读范围。

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

当 Agent 通过 `read_file` 工具读取 `/home/gem/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. 启动阶段：`_readable_skills` = [`pro-skill`, `advanced-skill`, `base-skill`]（自动展开依赖链）
2. Agent 首次调用任何 skill 时：所有三个 Skill 都可读
3. 当 Agent 读取 `pro-skill/SKILL.md` 时：触发激活，工具和 MCP 依赖被加载

## 权限管理

Skills 使用 `source_type`、`share_config` 和 `enabled` 控制来源、共享范围和启用状态。

| 字段 | 说明 |
|------|------|
| `source_type` | `builtin`、`upload` 或 `remote` |
| `share_config.access_level` | `global`、`department` 或 `user` |
| `enabled` | 是否允许在 Agent 配置与运行时使用 |

访问与管理规则：

| 用户 | 可见 / 可用 | 可管理 |
|------|-------------|--------|
| 超级管理员 / 管理员 | 可查看可管理或已启用且可访问的 Skills | 可管理所有非内置 Skills；可启停内置 Skills |
| 普通用户 | 可查看已启用且对自己可访问的 Skills，也可安装自己的私有 Skill | 可管理自己创建的非内置 Skills |
| 内置 Skills | 默认全局共享并启用 | 管理员可启停；不允许删除或直接编辑文件 |

共享范围限制：

- `global`：所有用户可访问
- `department`：指定部门用户可访问
- `user`：指定用户可访问；普通用户安装时只能选择个人范围

管理员和普通用户在创建或编辑 Agent 时，都只能从自己可访问且启用的 Skills 中选择能力。

## 运行时行为

### Agent 如何使用 Skills

1. **提示词注入**：系统在每次模型请求时动态注入可用 Skills 的描述（请求级注入，避免污染 runtime context）
2. **文件访问**：Skills 目录以只读方式挂载到 `/home/gem/skills/<slug>/...`
3. **工具调用**：当 Agent 需要使用某个 Skill 时，会先读取对应的 SKILL.md 了解使用方法

### 文件操作限制

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

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

### 会话隔离

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

## 最佳实践

### Skill 命名规范

- `slug` 使用小写字母、数字和短横线，不能连续短横线
- `slug` 应具有描述性，如 `weather-query`、`sql-reporter`
- `name` 用于展示，可比 `slug` 更自然，例如 `Word / DOCX`
- 避免过长的 `name` 和 `slug`

### 依赖管理建议

- **保持依赖链简洁**：层级不宜过深，一般 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. 远程来源的 Skill 可重新解析并确认安装，形成新的导入结果

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

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

---

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