技能 - Zeus

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

参考: Anthropic Skills · Agent Skills

三阶段渐进式加载

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

阶段	时机	加载内容	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

<!-- 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 指令内容。

---
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 生态。

文件结构

{
  "env": {
    "GEMINI_API_KEY": "AIzaSy...",
    "OPENAI_API_KEY": "sk-...",
    "UNIFYLLM_API_KEY": "sk-..."
  }
}

与 OpenClaw 的 env 块结构对齐，扁平 key-value 格式。

读取示例

Python:

import json
with open('/home/user/.zeus.json') as f:
    config = json.load(f)
api_key = config['env']['GEMINI_API_KEY']

Node.js:

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）

典型流程：

Skill 激活配置

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

{
  "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，它们根据节点连接状态动态切换提示词内容：这种机制确保：

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 侧重于外部系统集成的提示词模板。

开始使用

基础概念

核心能力

基础设施

渠道

技能

三阶段渐进式加载

System Prompt 中的体现

SKILL.md 格式

元数据字段

目录结构

Skill 来源

存储

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

文件结构

读取示例

兼容性

内置 Skills

chrome-extension

desktop-operator

skill-creator

Skill Tools（Agent 侧工具）

Skill 激活配置

Skills 管理 API

Discovery 阶段

Activation 阶段

Execution 阶段

CRUD

Storage 同步

Connector Skills 渐进式披露

Skills vs MCP Prompts

​三阶段渐进式加载

​System Prompt 中的体现

​SKILL.md 格式

​元数据字段

​目录结构

​Skill 来源

​存储

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

​文件结构

​读取示例

​兼容性

​内置 Skills

​chrome-extension

​desktop-operator

​skill-creator

​Skill Tools（Agent 侧工具）

​Skill 激活配置

​Skills 管理 API

​Discovery 阶段

​Activation 阶段

​Execution 阶段

​CRUD

​Storage 同步

​Connector Skills 渐进式披露

​Skills vs MCP Prompts

三阶段渐进式加载

System Prompt 中的体现

SKILL.md 格式

元数据字段

目录结构

Skill 来源

存储

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

文件结构

读取示例

兼容性

内置 Skills

chrome-extension

desktop-operator

skill-creator

Skill Tools（Agent 侧工具）

Skill 激活配置

Skills 管理 API

Discovery 阶段

Activation 阶段

Execution 阶段

CRUD

Storage 同步

Connector Skills 渐进式披露

Skills vs MCP Prompts