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 字段关联文件系统目录与数据库记录

不能直接在文件系统创建

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

创建方式

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

推荐 Skill 安装：在 Skills 管理页的推荐分组点击 +，系统会拉取对应远程来源并生成安装草稿
ZIP / SKILL.md 上传：上传后先解析为安装草稿，确认共享范围后再写入正式 Skills 存储和数据库
远程仓库安装：填写 skills 仓库地址、ModelScope Skill 地址或合集地址，后端调用 npx skills 下载并解析为安装草稿，确认后导入系统
在线编辑：对已有且可管理的 Skill 在线创建目录、编辑文件和维护依赖
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：

方式一：从推荐列表安装

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

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

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

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

系统会自动：

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

方式三：从远程来源安装

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

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

系统会在后端：

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

ModelScope 合集适合批量安装

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

方式四：在线编辑已有 Skill

在 Skills 管理页面，你可以：

新建目录或文件
在线编辑文本文件（支持 .md、.py、.js、.json 等格式）
直接在网页上修改 SKILL.md 内容

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

远程安装不会把 ~/.agents/skills 作为系统主存储

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

依赖系统

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

依赖类型

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

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

渐进式加载机制

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

阶段一：会话启动

当 Agent 会话启动时，系统会：

在创建 Graph 前读取已过滤的 context.skills 列表
递归展开 skill_dependencies，派生 _prompt_skills 和 _readable_skills
将 _prompt_skills 对应的技能说明注入到系统提示词中

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

阶段二：技能激活

当 Agent 通过 read_file 工具读取 /home/gem/skills/<slug>/SKILL.md 时，视为"激活"该技能。系统会：

验证该技能在可见列表中
将其添加到 activated_skills 列表
后续的模型调用会使用激活列表来加载依赖

阶段三：按需加载

每次模型调用时，系统会：

检查 activated_skills 中的技能
收集这些技能的 tool_dependencies 和 mcp_dependencies
动态将需要的工具和 MCP 服务添加到可用工具集中

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

依赖声明示例

假设我们有三个 Skills：

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

当在 Agent 配置中只选择 pro-skill 时：

启动阶段：_readable_skills = [pro-skill, advanced-skill, base-skill]（自动展开依赖链）
Agent 首次调用任何 skill 时：所有三个 Skill 都可读
当 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

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

文件操作限制

运行时 /home/gem/skills 路径有以下限制：

只读：Agent 只能读取文件内容
禁止写入：不能创建、修改或删除文件
路径安全：所有路径都经过安全校验，防止目录穿越攻击

虚拟文件系统限制

当前 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：请检查以下几点：

Skill 的 slug 是否正确配置在 Agent 的 context.skills 中
SKILL.md 是否存在且 frontmatter 格式正确
如果使用了依赖，确保依赖链完整

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

A：可以通过以下方式：

导出当前 Skill，修改后重新导入
在 Skills 管理页面在线编辑文件
远程来源的 Skill 可重新解析并确认安装，形成新的导入结果

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

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

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

Skills 管理系统 ​

为什么需要 Skills ​

架构设计 ​

存储结构 ​

创建方式 ​

Skills 来源 ​

快速开始 ​

创建你的第一个 Skill ​

导入 Skill ​

依赖系统 ​

依赖类型 ​

渐进式加载机制 ​

依赖声明示例 ​

权限管理 ​

运行时行为 ​

Agent 如何使用 Skills ​

文件操作限制 ​

会话隔离 ​

最佳实践 ​

Skill 命名规范 ​

依赖管理建议 ​

SKILL.md 编写技巧 ​

常见问题 ​