Wenjie Zhang 62bb928064 refactor: 更新文档部署说明

- 移除对于双版本文档的支持，更加清晰
- 将 docs 的入口从根目录移动到子目录

2026-03-24 11:09:46 +08:00

11 KiB

Raw Blame History

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：

ZIP 导入（推荐）：将 Skill 目录打包成 ZIP，通过管理界面上传导入
在线创建：通过 Skills 管理页面在线创建目录和文件
手动导入：直接操作数据库（不推荐，需要手动同步文件系统和数据库）

Skills 来源

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

Anthropic 官方 Tools：https://github.com/anthropics/skills 可以参考其 skills 的组织方式和提示词设计
社区 Skills：各平台分享的 Agent 提示词模板
自定义开发：根据业务需求自行开发

快速开始

创建你的第一个 Skill

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

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

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

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

# Skill 使用说明

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

## 功能列表

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

## 使用示例

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

Frontmatter 字段说明：

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

导入 Skill

有两种方式可以导入 Skill：

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

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

系统会自动：

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

方式二：在线创建

在 Skills 管理页面，你可以：

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

依赖系统

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

依赖类型

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

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

渐进式加载机制

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

阶段一：会话启动

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

读取 Agent 配置中的 context.skills 列表
递归展开 skill_dependencies，构建完整的可见技能集（visible_skills）
将可见技能列表注入到系统提示词中

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

阶段二：技能激活

当 Agent 通过 read_file 工具读取 /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 时：

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

权限管理

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

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

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

运行时行为

Agent 如何使用 Skills

提示词注入：系统会在 Agent 的系统提示词开头自动插入可用 Skills 的描述
文件访问：Skills 目录以只读方式挂载到 /skills/<slug>/...
工具调用：当 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 编写技巧

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

# 技能名称

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

## 何时使用

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

## 使用方法

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

## 示例

具体的使用示例...

常见问题

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

A：请检查以下几点：

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

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

A：可以通过以下方式：

导出当前 Skill，修改后重新导入
在 Skills 管理页面在线编辑文件
直接修改文件系统中的内容（需要重启服务使缓存失效）

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

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

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

11 KiB Raw Blame History Unescape Escape