> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 技能

> Zeus Skills 渐进式指令系统 — 三阶段加载、Connector Skills、Skill Tools

Skills 是动态加载的指令包，用于增强 Agent 的专业能力。Zeus 采用 **渐进式加载（Progressive Disclosure）** 机制，在启动时只加载元数据，按需加载完整内容，最大化节省 Token 开销。

> 参考: [Anthropic Skills](https://github.com/anthropics/skills) · [Agent Skills](https://agentskills.io/what-are-skills)

***

## 三阶段渐进式加载

Skills 的加载分为三个阶段，逐步披露内容：

```mermaid theme={null}
graph LR
    subgraph P1["Phase 1: Discovery"]
        direction TB
        p1_desc["启动时扫描目录<br/>只解析 YAML frontmatter<br/>存储 SkillMeta"]
    end

    subgraph P2["Phase 2: Activation"]
        direction TB
        p2_desc["用户请求匹配时<br/>加载完整 SKILL.md<br/>缓存 Skill 对象"]
    end

    subgraph P3["Phase 3: Execution"]
        direction TB
        p3_desc["执行时按需加载<br/>scripts/ 脚本<br/>references/ 文档"]
    end

    P1 -->|"匹配触发"| P2
    P2 -->|"需要资源"| P3
```

| 阶段             | 时机             | 加载内容                                | Token 开销 |
| -------------- | -------------- | ----------------------------------- | -------- |
| **Discovery**  | 应用启动           | YAML frontmatter（name, description） | 极低       |
| **Activation** | 用户请求匹配 or 显式激活 | 完整 Markdown 指令内容                    | 中等       |
| **Execution**  | Agent 执行中需要    | scripts/、references/、assets/        | 按需       |

### System Prompt 中的体现

* **未显式指定 Skills**：System Prompt 只注入 Discovery 摘要（`<available_skills>` XML），Agent 可通过 `skill_activate` 工具按需加载
* **显式指定 Skills**：完整内容以 `<activated_skill>` XML 直接注入 System Prompt

```xml theme={null}
<!-- Discovery 模式：只有元数据 -->
<available_skills>
<skill name="skill-creator">Guide for creating effective skills...</skill>
<skill name="chrome-extension">控制用户浏览器执行自动化任务...</skill>
</available_skills>

<!-- Activation 模式：完整内容注入 -->
<activated_skill name="skill-creator">
...完整的 Markdown 指令...
</activated_skill>
```

***

## SKILL.md 格式

每个 Skill 是一个目录，包含 `SKILL.md` 文件，头部为 YAML frontmatter，后面是 Markdown 指令内容。

```markdown theme={null}
---
name: my-skill
description: 描述何时使用此 Skill
version: 1.0.0
author: Zeus Team
tags:
  - category1
  - category2
triggers:
  - 关键词1
  - keyword2
priority: 0
enabled: true
---

# Skill 指令内容

详细的 AI 指令、规则和示例...
```

### 元数据字段

| 字段            | 必需 | 类型         | 说明                        |
| ------------- | -- | ---------- | ------------------------- |
| `name`        | 是  | `string`   | Skill 唯一标识符               |
| `description` | 是  | `string`   | 描述何时使用此 Skill（供 Agent 判断） |
| `version`     | 否  | `string`   | 版本号，默认 `1.0.0`            |
| `author`      | 否  | `string`   | 作者                        |
| `tags`        | 否  | `string[]` | 标签列表，用于分类和筛选              |
| `triggers`    | 否  | `string[]` | 触发关键词，用于自动匹配用户消息          |
| `priority`    | 否  | `int`      | 优先级，数值越大越优先（默认 `0`）       |
| `enabled`     | 否  | `bool`     | 是否启用（默认 `true`）           |

### 目录结构

```
my-skill/
├── SKILL.md              # 主指令文件（必需）
├── SKILL_ENABLED.md      # 启用状态的指令（Connector Skill 专用）
├── scripts/              # 可执行脚本（Phase 3 按需加载）
│   ├── init_skill.py
│   └── package_skill.py
├── references/           # 参考文档（Phase 3 按需加载）
│   ├── output-patterns.md
│   └── workflows.md
└── assets/               # 静态资源
```

***

## Skill 来源

Zeus 支持多种 Skill 来源：

| 来源              | 枚举值       | 说明                           |
| --------------- | --------- | ---------------------------- |
| **Local**       | `local`   | 本地文件系统（`repository/skills/`） |
| **Bundled**     | `bundled` | 内置预装                         |
| **User Upload** | `upload`  | 用户上传（通过 API 或 SKILL.md 文件）   |
| **Hub**         | `hub`     | Skills Hub（社区共享）             |
| **Remote**      | `remote`  | 远程 URL                       |

### 存储

| 类型        | 存储位置                                       | 说明                     |
| --------- | ------------------------------------------ | ---------------------- |
| 内置 Skills | `repository/skills/`                       | 随代码部署，启动时 Discovery    |
| 用户 Skills | Supabase Storage `users/{user_id}/skills/` | 用户级别，通过 sync API 同步到内存 |

***

## 沙箱配置文件（.zeus.json）

Skill 在沙箱中执行时，可能需要访问用户配置的 API 密钥。Zeus 会将用户在设置页面配置的密钥自动写入沙箱的 `/home/user/.zeus.json`，同时写入 `/home/user/.openclaw.json` 以兼容社区 Skill 生态。

### 文件结构

```json theme={null}
{
  "env": {
    "GEMINI_API_KEY": "AIzaSy...",
    "OPENAI_API_KEY": "sk-...",
    "UNIFYLLM_API_KEY": "sk-..."
  }
}
```

与 [OpenClaw](https://docs.openclaw.ai/help/environment) 的 `env` 块结构对齐，扁平 key-value 格式。

### 读取示例

**Python:**

```python theme={null}
import json
with open('/home/user/.zeus.json') as f:
    config = json.load(f)
api_key = config['env']['GEMINI_API_KEY']
```

**Node.js:**

```javascript theme={null}
const config = JSON.parse(require('fs').readFileSync('/home/user/.zeus.json', 'utf-8'))
const apiKey = config.env.GEMINI_API_KEY
```

### 兼容性

| 文件                          | 说明                       |
| --------------------------- | ------------------------ |
| `/home/user/.zeus.json`     | Zeus 标准配置文件              |
| `/home/user/.openclaw.json` | 社区兼容，内容与 `.zeus.json` 一致 |

***

## 内置 Skills

### chrome-extension

| 字段  | 值                                           |
| --- | ------------------------------------------- |
| 类型  | Connector Skill                             |
| 描述  | 控制用户浏览器执行自动化任务（打开网页、点击、填写表单、截图等）            |
| 触发词 | 打开网页, 浏览器, 搜索, 点击, 截图, browser, navigate... |
| 标签  | `browser`, `automation`, `web`, `connector` |

Browser Operator 采用 **渐进式披露**：

* **未连接浏览器扩展**：加载 `SKILL.md`（引导用户安装/连接扩展）
* **已连接浏览器扩展**：加载 `SKILL_ENABLED.md`（完整的浏览器工具文档）

### desktop-operator

| 字段  | 值                                             |
| --- | --------------------------------------------- |
| 类型  | Connector Skill                               |
| 描述  | 在用户本地电脑上执行 Shell 命令（涵盖 git、npm、文件操作等）         |
| 触发词 | 桌面, 终端, shell, git, npm, 命令, desktop...       |
| 标签  | `desktop`, `shell`, `automation`, `connector` |

Desktop Operator 同样采用渐进式披露，根据桌面应用连接状态切换 `SKILL.md` / `SKILL_ENABLED.md`。

### skill-creator

| 字段  | 值                                                                                                               |
| --- | --------------------------------------------------------------------------------------------------------------- |
| 类型  | Development Skill                                                                                               |
| 描述  | 引导创建新的 Skill，提供最佳实践和模板                                                                                          |
| 触发词 | create skill, new skill, 创建技能, 新技能...                                                                           |
| 标签  | `skill`, `creator`, `development`, `agent`                                                                      |
| 资源  | `scripts/init_skill.py`, `scripts/package_skill.py`, `references/output-patterns.md`, `references/workflows.md` |

***

## Skill Tools（Agent 侧工具）

Agent 在运行时可以通过以下工具按需操作 Skills：

| 工具                                                        | 说明                                        |
| --------------------------------------------------------- | ----------------------------------------- |
| `skill_discover(tag?)`                                    | 列出所有可用 Skills，支持按标签筛选（Phase 1: Discovery） |
| `skill_activate(skill_name)`                              | 激活指定 Skill，加载完整内容（Phase 2: Activation）    |
| `skill_execute(skill_name, resource_type, resource_name)` | 加载 Skill 的脚本/参考文档（Phase 3: Execution）     |

**典型流程：**

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Agent
    participant SkillsManager

    User->>Agent: "帮我做代码审查"
    Note over Agent: System Prompt 包含<br/>available_skills 摘要
    Agent->>SkillsManager: skill_activate("code-review")
    SkillsManager-->>Agent: 完整 Skill 内容
    Note over Agent: 按照 Skill 指令执行
    Agent->>User: 专业的代码审查结果
```

***

## Skill 激活配置

前端可以通过 `SkillActivation` 配置 Skills 的激活方式：

```json theme={null}
{
  "skills": {
    "skill_names": ["chrome-extension"],
    "auto_match": true,
    "max_skills": 3
  }
}
```

| 字段            | 类型         | 说明                      |
| ------------- | ---------- | ----------------------- |
| `skill_names` | `string[]` | 显式激活的 Skill 名称列表        |
| `auto_match`  | `bool`     | 是否根据用户消息自动匹配（默认 `true`） |
| `max_skills`  | `int`      | 最大激活数量（默认 `3`）          |

**匹配优先级**：显式指定 > 自动匹配（按 `priority` 降序）

***

## Skills 管理 API

### Discovery 阶段

| 方法    | 路径                  | 说明                                           |
| ----- | ------------------- | -------------------------------------------- |
| `GET` | `/api/skills`       | 获取所有 Skill 元数据（支持 `enabled_only`, `tags` 筛选） |
| `GET` | `/api/skills/stats` | 获取统计信息（discovered, activated, enabled）       |
| `GET` | `/api/skills/user`  | 获取用户在 Supabase Storage 中的 Skills             |

### Activation 阶段

| 方法     | 路径                            | 说明                  |
| ------ | ----------------------------- | ------------------- |
| `GET`  | `/api/skills/{name}`          | 获取 Skill 详情（加载完整内容） |
| `POST` | `/api/skills/{name}/activate` | 显式激活 Skill          |

### Execution 阶段

| 方法    | 路径                                           | 说明                                  |
| ----- | -------------------------------------------- | ----------------------------------- |
| `GET` | `/api/skills/{name}/resources/{type}/{file}` | 获取 Skill 资源（script/reference/asset） |

### CRUD

| 方法       | 路径                          | 说明                     |
| -------- | --------------------------- | ---------------------- |
| `POST`   | `/api/skills`               | 创建 Skill（JSON 请求体）     |
| `POST`   | `/api/skills/upload`        | 上传 SKILL.md 文件创建 Skill |
| `PUT`    | `/api/skills/{name}`        | 更新 Skill               |
| `DELETE` | `/api/skills/{name}`        | 删除 Skill               |
| `POST`   | `/api/skills/{name}/toggle` | 切换启用/禁用状态              |
| `POST`   | `/api/skills/reload`        | 从目录重新加载                |

### Storage 同步

| 方法     | 路径                     | 说明                          |
| ------ | ---------------------- | --------------------------- |
| `POST` | `/api/skills/sync`     | 同步单个 Skill（Supabase → 内存缓存） |
| `POST` | `/api/skills/sync-all` | 同步用户所有 Skills               |

***

## Connector Skills 渐进式披露

Browser Operator 和 Desktop Operator 是特殊的 **Connector Skills**，它们根据节点连接状态动态切换提示词内容：

```mermaid theme={null}
graph TD
    check["检查节点连接状态"] -->|"Extension 已连接"| enabled["加载 SKILL_ENABLED.md<br/>完整工具文档 + 使用指南"]
    check -->|"Extension 未连接"| disabled["加载 SKILL.md<br/>引导用户安装/连接扩展"]

    enabled --> inject["注入 System Prompt"]
    disabled --> inject
```

这种机制确保：

* Agent **不会** 在没有可用节点时调用浏览器/桌面工具
* Agent **知道如何** 引导用户连接缺失的节点
* 已连接时获得完整的工具使用文档

***

## Skills vs MCP Prompts

| 特性  | Skills                                     | MCP Prompts    |
| --- | ------------------------------------------ | -------------- |
| 来源  | 本地文件 / Supabase Storage / Hub              | MCP Server     |
| 加载  | 渐进式三阶段（Discovery → Activation → Execution） | 启动时加载          |
| 触发  | 关键词自动匹配 or 显式激活                            | 显式调用           |
| 参数化 | 不支持动态参数                                    | 支持 `arguments` |
| 资源  | 支持 scripts/、references/、assets/            | 不支持            |
| 管理  | 文件系统 + REST API + Supabase Storage         | 通过 MCP 协议      |
| 用途  | 增强 Agent 专业能力和行为模式                         | 外部系统的提示词模板     |

两者可以同时使用，互为补充。Skills 侧重于 Agent 的行为指令，MCP Prompts 侧重于外部系统集成的提示词模板。