# Skills 使用指南

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

---

## Skill 分类

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

### Core Skill

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

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

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

**加载方式**：
- 框架自动注入到 System Prompt
- `load_skills_from_dir()` 总是自动加载 `agent/skills/` 中的所有 skills（包括 `core.md`）

### 内置 Skill

框架提供的特定领域能力，按需加载：

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

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

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

### 自定义 Skill

项目特定的能力，按需加载：

**位置**：`./skills/{name}.md`

**加载方式**：
1. 通过 `skills_dir` 参数在 Agent 启动时加载到 System Prompt
2. 通过 `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 调用

**方式 1：自动加载到 System Prompt**

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

# 加载自定义 skills 到 System Prompt
runner = AgentRunner(
    llm_call=create_gemini_llm_call(os.getenv("GEMINI_API_KEY")),
    skills_dir="./skills",  # 可选：加载额外的自定义 skills
)

# 结果：
# - agent/skills/core.md 自动加载（总是）
# - agent/skills/ 中的其他 skills 自动加载
# - ./skills/ 中的 skills 也会自动加载
```

**方式 2：运行时动态加载**

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

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

async for item in runner.run(
    task="帮我从网站提取数据",
    model="gemini-2.0-flash-exp"
):
    # Agent 会自动调用 skill 工具加载需要的 skills
    pass
```

**Agent 工作流**：
1. Agent 启动时自动加载 `agent/skills/` 中的所有 skills（包括 `core.md`）
2. 如果提供了 `skills_dir`，也会加载自定义 skills 到 System Prompt
3. Agent 接收任务
4. Agent 可以调用 `list_skills()` 查看可用 skills
5. Agent 可以调用 `skill(skill_name="browser-use")` 动态加载特定 skill
6. Skill 内容注入到对话历史
7. Agent 根据 skill 指导完成任务

### 4. 手动测试

```python
from agent.tools.builtin.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 加载机制

### 自动加载（Agent 启动时）

```python
# load_skills_from_dir() 自动加载内置 skills
runner = AgentRunner(
    llm_call=my_llm,
    # 不需要指定 skills_dir，内置 skills 会自动加载
)

# 结果：agent/skills/ 中的所有 skills 都会被加载到 System Prompt
```

### 可选加载额外的自定义 Skills

```python
runner = AgentRunner(
    llm_call=my_llm,
    skills_dir="./my-custom-skills",  # 可选：加载额外的自定义 skills
)

# 结果：agent/skills/ + ./my-custom-skills/ 中的所有 skills 都会被加载
```

### 动态加载（运行时）

Agent 可以通过 `skill` 工具运行时动态加载特定的 skill：

```python
# Agent 调用
skill(skill_name="browser-use")

# 搜索路径（优先级）：
# 1. ./skills/browser-use.md         ← 项目自定义
# 2. ./agent/skills/browser-use/     ← 框架内置
```

**实现位置**：
- `agent/skill/skill_loader.py:load_skills_from_dir()` - 自动加载机制
- `agent/tools/builtin/skill.py` - skill 工具（动态加载）

详见 [`SKILLS_SYSTEM.md`](../SKILLS_SYSTEM.md)

## Skill 工具 API

### `skill` 工具

加载指定的 skill 文档。

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

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

### `list_skills` 工具

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

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

**实现位置**：`agent/tools/builtin/skill.py`

## 环境变量

可以设置默认 skills 目录：

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

## 参考

- 完整文档：[`SKILLS_SYSTEM.md`](../SKILLS_SYSTEM.md)
- 示例：`examples/feature_extract/run.py`
- Skill 文件：`agent/skills/` 目录
- 工具实现：`agent/tools/builtin/skill.py`
- 加载器实现：`agent/skill/skill_loader.py`