> ## 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.

# Skills

> Zeus Skills Progressive Instruction System — Three-Phase Loading, Connector Skills, Skill Tools

Skills are dynamically loaded instruction packages that enhance the Agent's specialized capabilities. Zeus employs a **Progressive Disclosure** mechanism that loads only metadata at startup and loads full content on demand, maximizing Token savings.

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

***

## Three-Phase Progressive Loading

Skills loading is divided into three phases, progressively disclosing content:

```mermaid theme={null}
graph LR
    subgraph P1["Phase 1: Discovery"]
        direction TB
        p1_desc["Scan directory at startup<br/>Parse YAML frontmatter only<br/>Store SkillMeta"]
    end

    subgraph P2["Phase 2: Activation"]
        direction TB
        p2_desc["When user request matches<br/>Load full SKILL.md<br/>Cache Skill object"]
    end

    subgraph P3["Phase 3: Execution"]
        direction TB
        p3_desc["Load on demand during execution<br/>scripts/ scripts<br/>references/ documents"]
    end

    P1 -->|"Match triggered"| P2
    P2 -->|"Resources needed"| P3
```

| Phase          | Timing                                    | Loaded Content                       | Token Cost |
| -------------- | ----------------------------------------- | ------------------------------------ | ---------- |
| **Discovery**  | Application startup                       | YAML frontmatter (name, description) | Very low   |
| **Activation** | User request match or explicit activation | Full Markdown instruction content    | Medium     |
| **Execution**  | Agent needs resources during execution    | scripts/, references/, assets/       | On demand  |

### Representation in System Prompt

* **No Skills explicitly specified**: System Prompt only injects Discovery summaries (`<available_skills>` XML); Agent can activate on demand via the `skill_activate` tool
* **Skills explicitly specified**: Full content is directly injected into System Prompt as `<activated_skill>` XML

```xml theme={null}
<!-- Discovery mode: metadata only -->
<available_skills>
<skill name="skill-creator">Guide for creating effective skills...</skill>
<skill name="chrome-extension">Control user browser for automated tasks...</skill>
</available_skills>

<!-- Activation mode: full content injected -->
<activated_skill name="skill-creator">
...full Markdown instructions...
</activated_skill>
```

***

## SKILL.md Format

Each Skill is a directory containing a `SKILL.md` file with a YAML frontmatter header followed by Markdown instruction content.

```markdown theme={null}
---
name: my-skill
description: Describes when to use this Skill
version: 1.0.0
author: Zeus Team
tags:
  - category1
  - category2
triggers:
  - keyword1
  - keyword2
priority: 0
enabled: true
---

# Skill Instruction Content

Detailed AI instructions, rules, and examples...
```

### Metadata Fields

| Field         | Required | Type       | Description                                                   |
| ------------- | -------- | ---------- | ------------------------------------------------------------- |
| `name`        | Yes      | `string`   | Unique Skill identifier                                       |
| `description` | Yes      | `string`   | Describes when to use this Skill (for Agent judgment)         |
| `version`     | No       | `string`   | Version number, defaults to `1.0.0`                           |
| `author`      | No       | `string`   | Author                                                        |
| `tags`        | No       | `string[]` | Tag list for categorization and filtering                     |
| `triggers`    | No       | `string[]` | Trigger keywords for automatic matching against user messages |
| `priority`    | No       | `int`      | Priority; higher values take precedence (default `0`)         |
| `enabled`     | No       | `bool`     | Whether enabled (default `true`)                              |

### Directory Structure

```
my-skill/
├── SKILL.md              # Main instruction file (required)
├── SKILL_ENABLED.md      # Enabled state instructions (Connector Skill specific)
├── scripts/              # Executable scripts (Phase 3, loaded on demand)
│   ├── init_skill.py
│   └── package_skill.py
├── references/           # Reference documents (Phase 3, loaded on demand)
│   ├── output-patterns.md
│   └── workflows.md
└── assets/               # Static resources
```

***

## Skill Sources

Zeus supports multiple Skill sources:

| Source          | Enum Value | Description                              |
| --------------- | ---------- | ---------------------------------------- |
| **Local**       | `local`    | Local filesystem (`repository/skills/`)  |
| **Bundled**     | `bundled`  | Pre-installed built-in                   |
| **User Upload** | `upload`   | User-uploaded (via API or SKILL.md file) |
| **Hub**         | `hub`      | Skills Hub (community shared)            |
| **Remote**      | `remote`   | Remote URL                               |

### Storage

| Type            | Storage Location                           | Description                               |
| --------------- | ------------------------------------------ | ----------------------------------------- |
| Built-in Skills | `repository/skills/`                       | Deployed with code, discovered at startup |
| User Skills     | Supabase Storage `users/{user_id}/skills/` | User-level, synced to memory via sync API |

***

## Sandbox Configuration File (.zeus.json)

When Skills execute in the sandbox, they may need access to user-configured API keys. Zeus automatically writes the keys configured in the user's settings to `/home/user/.zeus.json` in the sandbox, along with `/home/user/.openclaw.json` for compatibility with the community Skill ecosystem.

### File Structure

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

Aligned with the [OpenClaw](https://docs.openclaw.ai/help/environment) `env` block structure, using flat key-value format.

### Reading Examples

**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
```

### Compatibility

| File                        | Description                                             |
| --------------------------- | ------------------------------------------------------- |
| `/home/user/.zeus.json`     | Zeus standard configuration file                        |
| `/home/user/.openclaw.json` | Community compatible, content identical to `.zeus.json` |

***

## Built-in Skills

### chrome-extension

| Field       | Value                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------ |
| Type        | Connector Skill                                                                            |
| Description | Control user browser for automated tasks (open pages, click, fill forms, screenshot, etc.) |
| Triggers    | open page, browser, search, click, screenshot, navigate...                                 |
| Tags        | `browser`, `automation`, `web`, `connector`                                                |

Browser Operator uses **progressive disclosure**:

* **Browser extension not connected**: Loads `SKILL.md` (guides user to install/connect extension)
* **Browser extension connected**: Loads `SKILL_ENABLED.md` (complete browser tool documentation)

### desktop-operator

| Field       | Value                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------ |
| Type        | Connector Skill                                                                            |
| Description | Execute Shell commands on user's local machine (including git, npm, file operations, etc.) |
| Triggers    | desktop, terminal, shell, git, npm, command...                                             |
| Tags        | `desktop`, `shell`, `automation`, `connector`                                              |

Desktop Operator also uses progressive disclosure, switching between `SKILL.md` / `SKILL_ENABLED.md` based on desktop application connection status.

### skill-creator

| Field       | Value                                                                                                           |
| ----------- | --------------------------------------------------------------------------------------------------------------- |
| Type        | Development Skill                                                                                               |
| Description | Guide creation of new Skills, providing best practices and templates                                            |
| Triggers    | create skill, new skill...                                                                                      |
| Tags        | `skill`, `creator`, `development`, `agent`                                                                      |
| Resources   | `scripts/init_skill.py`, `scripts/package_skill.py`, `references/output-patterns.md`, `references/workflows.md` |

***

## Skill Tools (Agent-Side Tools)

The Agent can operate Skills on demand at runtime through the following tools:

| Tool                                                      | Description                                                                 |
| --------------------------------------------------------- | --------------------------------------------------------------------------- |
| `skill_discover(tag?)`                                    | List all available Skills, with optional tag filtering (Phase 1: Discovery) |
| `skill_activate(skill_name)`                              | Activate a specified Skill, loading its full content (Phase 2: Activation)  |
| `skill_execute(skill_name, resource_type, resource_name)` | Load a Skill's scripts/reference documents (Phase 3: Execution)             |

**Typical Flow:**

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

    User->>Agent: "Help me do a code review"
    Note over Agent: System Prompt contains<br/>available_skills summary
    Agent->>SkillsManager: skill_activate("code-review")
    SkillsManager-->>Agent: Full Skill content
    Note over Agent: Execute following Skill instructions
    Agent->>User: Professional code review results
```

***

## Skill Activation Configuration

The frontend can configure Skills activation via `SkillActivation`:

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

| Field         | Type       | Description                                                            |
| ------------- | ---------- | ---------------------------------------------------------------------- |
| `skill_names` | `string[]` | List of explicitly activated Skill names                               |
| `auto_match`  | `bool`     | Whether to automatically match based on user messages (default `true`) |
| `max_skills`  | `int`      | Maximum number of activated Skills (default `3`)                       |

**Matching Priority**: Explicitly specified > Auto-matched (sorted by `priority` descending)

***

## Skills Management API

### Discovery Phase

| Method | Path                | Description                                                        |
| ------ | ------------------- | ------------------------------------------------------------------ |
| `GET`  | `/api/skills`       | Get all Skill metadata (supports `enabled_only`, `tags` filtering) |
| `GET`  | `/api/skills/stats` | Get statistics (discovered, activated, enabled)                    |
| `GET`  | `/api/skills/user`  | Get user's Skills in Supabase Storage                              |

### Activation Phase

| Method | Path                          | Description                            |
| ------ | ----------------------------- | -------------------------------------- |
| `GET`  | `/api/skills/{name}`          | Get Skill details (loads full content) |
| `POST` | `/api/skills/{name}/activate` | Explicitly activate a Skill            |

### Execution Phase

| Method | Path                                         | Description                                 |
| ------ | -------------------------------------------- | ------------------------------------------- |
| `GET`  | `/api/skills/{name}/resources/{type}/{file}` | Get Skill resource (script/reference/asset) |

### CRUD

| Method   | Path                        | Description                          |
| -------- | --------------------------- | ------------------------------------ |
| `POST`   | `/api/skills`               | Create Skill (JSON request body)     |
| `POST`   | `/api/skills/upload`        | Upload SKILL.md file to create Skill |
| `PUT`    | `/api/skills/{name}`        | Update Skill                         |
| `DELETE` | `/api/skills/{name}`        | Delete Skill                         |
| `POST`   | `/api/skills/{name}/toggle` | Toggle enabled/disabled state        |
| `POST`   | `/api/skills/reload`        | Reload from directory                |

### Storage Sync

| Method | Path                   | Description                                   |
| ------ | ---------------------- | --------------------------------------------- |
| `POST` | `/api/skills/sync`     | Sync a single Skill (Supabase → memory cache) |
| `POST` | `/api/skills/sync-all` | Sync all user Skills                          |

***

## Connector Skills Progressive Disclosure

Browser Operator and Desktop Operator are special **Connector Skills** that dynamically switch prompt content based on node connection status:

```mermaid theme={null}
graph TD
    check["Check node connection status"] -->|"Extension connected"| enabled["Load SKILL_ENABLED.md<br/>Full tool documentation + usage guide"]
    check -->|"Extension not connected"| disabled["Load SKILL.md<br/>Guide user to install/connect extension"]

    enabled --> inject["Inject into System Prompt"]
    disabled --> inject
```

This mechanism ensures:

* The Agent **will not** call browser/desktop tools when no nodes are available
* The Agent **knows how to** guide users to connect missing nodes
* When connected, the Agent receives complete tool usage documentation

***

## Skills vs MCP Prompts

| Feature          | Skills                                                       | MCP Prompts                      |
| ---------------- | ------------------------------------------------------------ | -------------------------------- |
| Source           | Local files / Supabase Storage / Hub                         | MCP Server                       |
| Loading          | Progressive three-phase (Discovery → Activation → Execution) | Loaded at startup                |
| Triggering       | Keyword auto-match or explicit activation                    | Explicit invocation              |
| Parameterization | No dynamic parameters                                        | Supports `arguments`             |
| Resources        | Supports scripts/, references/, assets/                      | Not supported                    |
| Management       | Filesystem + REST API + Supabase Storage                     | Via MCP protocol                 |
| Purpose          | Enhance Agent specialized capabilities and behavior patterns | External system prompt templates |

Both can be used simultaneously and complement each other. Skills focus on Agent behavioral instructions, while MCP Prompts focus on prompt templates for external system integration.