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

加载方式：

通过 skills_dir 参数在 Agent 启动时加载到 System Prompt
通过 skill 工具运行时按需加载

普通 Skill 文件格式

---
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 目录

mkdir skills

2. 添加 skill 文件

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

3. Agent 调用

方式 1：自动加载到 System Prompt

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：运行时动态加载

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 工作流：

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

4. 手动测试

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 启动时）

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

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

可选加载额外的自定义 Skills

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

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

动态加载（运行时）

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

# 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

Skill 工具 API

`skill` 工具

加载指定的 skill 文档。

参数：

skill_name (str): Skill 名称，如 "browser-use"

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

`list_skills` 工具

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

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

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

环境变量

可以设置默认 skills 目录：

# .env
SKILLS_DIR=./skills

参考

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

skills.md 5.5 KB Link permanente Histórico Em bruto