---
title: "技能"
---

技能（Skills）是一种可复用的「提示词包」，用于为 Agent 注入特定的领域知识、操作流程与脚本。本地技能加载/执行场景推荐使用 Google ADK 官方的 `load_skill_from_dir` / `SkillToolset` 方式接入；VeADK 旧的 `Agent(skills=..., skills_mode="local")` 本地入口仍保持兼容，但已标记为 deprecated。`skills_sandbox` 与 `aio_sandbox` 模式仍按原方式使用。

## 推荐：ADK SkillToolset

本地技能可直接通过 Google ADK 加载，并作为标准工具集传给 VeADK Agent：

```python
from google.adk.skills import load_skill_from_dir
from google.adk.tools.skill_toolset import SkillToolset
from veadk import Agent

skill = load_skill_from_dir("/abs/path/to/skills/kb-skill")
agent = Agent(
    tools=[SkillToolset(skills=[skill])],
)
```

这一路径下，技能加载、prompt 注入和工具暴露都由 ADK 处理。模型可见的工具包括 `list_skills`、`load_skill`、`load_skill_resource` 和 `run_skill_script`。如果技能依赖 `scripts/` 执行，请在 `SkillToolset` 或 Agent 上显式配置合适的 `code_executor`；VeADK 不会默认创建本地代码执行器。

云端 SkillHub / SkillSpace 技能推荐通过 VeADK 的 ADK Registry 接入。`search_skills` 会实时拉取远端技能列表，`get_skill` 会在需要某个技能时按需下载并加载：

```python
from google.adk.tools.skill_toolset import SkillToolset
from veadk import Agent
from veadk.skills import VeSkillRegistry

registry = VeSkillRegistry(skill_source_id=skill_space_id)
agent = Agent(
    tools=[SkillToolset(registry=registry)],
)
```

该方式不会在初始化阶段全量下载技能；缓存仅用于已下载的具体技能版本。远端 metadata 每次 search / get 都会重新拉取，因此远端版本变化后会按新版本重新下载。

## 技能目录结构

一个 ADK 本地技能由独立目录构成，目录中包含一个 `SKILL.md` 文件。`SKILL.md` 必须包含 `name` 与 `description` frontmatter，且目录名必须与 `name` 一致：

<Files>
  <Folder name="skills" defaultOpen>
    <Folder name="kb-skill" defaultOpen>
      <File name="SKILL.md" />
      <Folder name="references" />
      <Folder name="assets" />
      <Folder name="scripts" />
    </Folder>
  </Folder>
</Files>

```markdown title="skills/kb-skill/SKILL.md"
---
name: kb-skill
description: 查询知识库并整理答案的技能。
---

...正文部分（操作步骤、约束、脚本说明等）
```

## Deprecated：VeADK 旧本地入口

`Agent(skills=..., skills_mode="local")` 会继续保持旧行为，但该本地入口已 deprecated。无论 `skills` 传入本地目录还是远端技能源，只要最终以 `local` 模式执行，VeADK 都会走旧的本地加载路径：加载技能元信息、把技能列表写入 `instruction`，并挂载旧的 `SkillsToolset`。

VeADK `skills` 参数仍支持三种技能运行模式，其中仅 `local` 的旧本地加载/执行路径标记为 deprecated：

| 模式 | 说明 |
| :- | :- |
| `local` | Deprecated。技能由 VeADK 旧 `skills_tool` 和配套文件/Shell 工具加载，建议迁移到 ADK `SkillToolset`。 |
| `skills_sandbox` | 技能托管在云端技能空间（Skill Space），通过 `execute_skills` 工具在沙箱中执行。 |
| `aio_sandbox` | All-in-one 沙箱模式，适用于 AgentKit 托管的工具运行时。 |

未显式设置 `skills_mode` 时，VeADK 会根据运行环境自动推断：本地运行默认为 `local`；在 AgentKit 工具运行时中，会根据工具类型自动选择 `skills_sandbox` 或 `aio_sandbox`。

### 本地模式

在 `local` 模式下，向 `skills` 传入技能根目录的路径，并将 `skills_mode` 设置为 `local`：

```python
from veadk import Agent

agent = Agent(
    skills=["/abs/path/to/skills"],
    skills_mode="local",
)
```

Agent 在初始化时会加载技能元信息（`name` 与 `description`）并将其注入系统提示词，引导模型在合适的时机调用对应技能。本地模式下，VeADK 还会自动挂载一组配套工具（读写文件、编辑文件、执行 Shell 命令、注册技能等），供 Agent 在执行技能时使用。

### 沙箱模式

在 `skills_sandbox` 模式下，技能托管在云端技能空间。向 `skills` 传入云端技能空间标识，并引入 `execute_skills` 工具，Agent 会在需要时调用该工具在沙箱中执行所选技能：

```python
from veadk import Agent
from veadk.tools.builtin_tools.execute_skills import execute_skills

agent = Agent(
    skills=[skill_space_id],
    skills_mode="skills_sandbox",
    tools=[execute_skills],
)
```

### 技能检查清单（Checklist）

技能可在其定义中携带一份检查清单（checklist），用于约束 Agent 按步骤完成任务。开启后，Agent 在执行技能时需逐项完成检查项，并通过 `update_check_list` 工具将每一项标记为已完成：

```python
from veadk import Agent

agent = Agent(
    skills=["/abs/path/to/skills"],
    skills_mode="local",
    enable_skills_checklist=True,
)
```

当某个技能定义了 checklist 时，VeADK 会在该技能被调用时自动初始化所有检查项的状态，并在系统提示词中提示模型逐项完成。

### 动态加载技能

通过 `enable_dynamic_load_skills=True`，可在运行时动态发现并加载新的技能，而无需在 Agent 初始化时一次性声明全部技能：

```python
from veadk import Agent

agent = Agent(
    skills_mode="local",
    enable_dynamic_load_skills=True,
)
```

## 参数总览

| 参数 | 类型 | 说明 |
| :- | :- | :- |
| `skills` | `list[str]` | 技能列表，元素为本地技能根目录路径或云端技能空间标识；当 `skills_mode="local"` 时，该旧本地加载路径已 deprecated。 |
| `skills_mode` | `"local" \| "skills_sandbox" \| "aio_sandbox"` | 技能运行模式，缺省时自动推断；其中 `local` 旧路径已 deprecated，`skills_sandbox` / `aio_sandbox` 仍保持原用法。 |
| `enable_skills_checklist` | `bool` | 是否启用旧技能检查清单，默认 `False`。 |
| `enable_dynamic_load_skills` | `bool` | 是否启用旧技能的动态加载，默认 `False`。 |
