# Skills 使用指南

Skills 是 Agent 的领域知识库，存储在 Markdown 文件中。

---

## Skill 分类

| 类型 | 加载位置 | 加载时机 | 文件位置 |
|------|---------|---------|---------|
| **Core Skill** | System Prompt | Agent 启动时自动加载 | `agent/skills/core.md` |
| **普通 Skill** | 对话消息 | 模型调用 `skill` 工具时 | `agent/skills/{name}/` |

### Core Skill

核心系统功能，每个 Agent 都需要了解：

- Step 管理（计划、执行、进度）
- 其他系统级功能

**位置**：`agent/skills/core.md`

**加载方式**：框架自动注入到 System Prompt

### 普通 Skill

特定领域能力，按需加载：

- browser_use（浏览器自动化）
- 其他领域 skills

**位置**：`agent/skills/{name}/`

**加载方式**：模型调用 `skill` 工具

---

## 普通 Skill 文件格式

```markdown
---
name: browser-use
description: 浏览器自动化工具使用指南
category: web-automation
scope: agent:*
---

## When to use
- 需要访问网页、填写表单
- 需要截图或提取网页内容

## Guidelines
- 先运行 `browser-use state` 查看可点击元素
- 使用元素索引进行交互：`browser-use click 5`
- 每次操作后验证结果
```

**Frontmatter 字段**：
- `name`: Skill 名称（必填）
- `description`: 简短描述（必填）
- `category`: 分类（可选，默认 general）
- `scope`: 作用域（可选，默认 agent:*）

**章节**：
- `## When to use`: 适用场景列表
- `## Guidelines`: 指导原则列表

## 使用方法

### 1. 创建 skills 目录

```bash
mkdir skills
```

### 2. 添加 skill 文件

创建 `skills/browser-use.md` 文件，按照上述格式编写。

### 3. Agent 调用

Agent 在运行时可以调用 skill 工具：

```python
from agent import AgentRunner
from agent.llm.providers.gemini import create_gemini_llm_call
import os

runner = AgentRunner(
    llm_call=create_gemini_llm_call(os.getenv("GEMINI_API_KEY"))
)

async for event in runner.run(
    task="帮我从网站提取数据",
    tools=["skill", "list_skills", "bash"],
    model="gemini-2.0-flash-exp"
):
    if event.type == "conclusion":
        print(event.data["content"])
```

**Agent 工作流**：
1. Agent 接收任务
2. Agent 调用 `list_skills()` 查看可用 skills
3. Agent 调用 `skill(skill_name="browser-use")` 加载需要的 skill
4. Skill 内容注入到对话历史
5. Agent 根据 skill 指导完成任务

### 4. 手动测试

```python
from tools.skill import list_skills, skill

# 列出所有 skills
result = await list_skills()
print(result.output)

# 加载特定 skill
result = await skill(skill_name="browser-use")
print(result.output)
```

## Skill 工具

### `skill` 工具

加载指定的 skill 文档。

**参数**：
- `skill_name` (str): Skill 名称，如 "browser-use"

**返回**：Skill 的完整内容（Markdown 格式）

### `list_skills` 工具

列出所有可用的 skills，按 category 分组。

**返回**：Skills 列表，包含名称、ID 和简短描述

## 环境变量

可以设置默认 skills 目录：

```bash
# .env
SKILLS_DIR=./skills
```

## 参考

- 示例: `examples/skills_example.py`
- Skill 文件: `skills/` 目录
- 工具实现: `tools/skill.py`