> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 技能

技能是一种可复用的提示词包，用于为智能体注入特定的领域知识、操作流程与脚本。技能与 Google ADK 兼容：本地技能推荐通过 ADK 的 `SkillToolset` 接入，云端技能空间推荐通过 VeADK 的 `VeSkillRegistry` 接入。

## 本地技能

用 ADK 的 `load_skill_from_dir` 加载本地技能目录，并作为标准工具集传给智能体：

```python lines theme={null}
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])])
```

技能加载、提示词注入与工具暴露均由 ADK 处理，模型可见的工具包括 `list_skills`、`load_skill`、`load_skill_resource` 和 `run_skill_script`。若技能依赖 `scripts/` 中的脚本执行，需在 `SkillToolset` 或智能体上显式配置合适的 `code_executor`，VeADK 不会默认创建本地代码执行器。

## 云端技能空间

云端技能空间通过 `VeSkillRegistry` 接入，再交给 `SkillToolset`：

```python lines theme={null}
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)])
```

该方式不会在初始化时全量下载技能：`search_skills` 实时拉取远端技能列表，`get_skill` 在需要某个技能时按需下载并加载；远端版本变化后会按新版本重新下载。

## 技能目录结构

一个本地技能由独立目录构成，包含一个 `SKILL.md` 文件，并可包含 `references/`、`assets/`、`scripts/` 等子目录：

```text lines theme={null}
skills/
└── kb-skill/
    ├── SKILL.md
    ├── references/
    ├── assets/
    └── scripts/
```

`SKILL.md` 需在 frontmatter 中声明 `name` 与 `description`，且目录名必须与 `name` 一致：

```markdown SKILL.md lines theme={null}
---
name: kb-skill
description: 查询知识库并整理答案的技能。
---

正文部分……
```

## 旧本地入口（已废弃）

VeADK 旧的 `Agent(skills=..., skills_mode="local")` 本地入口仍保持兼容，但已废弃，建议迁移到上文的 `SkillToolset`。`skills_sandbox` 与 `aio_sandbox` 两种沙箱模式不受影响，仍按原方式使用：

| 模式 | 说明 |
| - | - |
| `local` | 已废弃。由 VeADK 旧路径加载本地技能，建议迁移到 ADK `SkillToolset`。 |
| `skills_sandbox` | 技能托管在云端技能空间，通过 `execute_skills` 工具在沙箱中执行。 |
| `aio_sandbox` | All-in-one 沙箱模式，适用于 AgentKit 托管的工具运行时。 |

沙箱模式示例：

```python lines theme={null}
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],
)
```