> ## 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/` 中的脚本执行，直接使用 ADK 的 `SkillToolset` 构造工具集时需要在 `SkillToolset` 或智能体上显式配置合适的 `code_executor`。

<Note>
  通过 Harness、CLI 生成的智能体代码或 AgentKit 会话能力服务加载技能时，VeADK 会自动为 `SkillToolset` 配置本地代码执行器，技能中的脚本可直接运行，无需额外配置。
</Note>

## 云端技能空间

云端技能空间通过 `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` 在需要某个技能时按需下载并加载；远端版本变化后会按新版本重新下载。

## Harness 技能中心

Harness 可以同时加载 Skill Hub 技能和 AgentKit 技能中心的技能空间。`skills` 中的普通名称或 slug 表示 Skill Hub 技能；`space:` 前缀表示技能中心的技能空间 ID。

技能中心需要可读取该技能空间及其对象存储内容的火山引擎凭证。本地运行时设置 `VOLCENGINE_ACCESS_KEY` 与 `VOLCENGINE_SECRET_KEY`，使用临时凭证时同时设置 `VOLCENGINE_SESSION_TOKEN`；VeFaaS 中也可以使用绑定 IAM Role 的临时凭证。

```bash lines theme={null}
cd my-harness
veadk harness add \
  --skills "data-visualization-cloud,space:ss-example"
```

生成的 `harness.yaml` 使用列表保存技能来源：

```yaml lines theme={null}
skills:
  - data-visualization-cloud
  - space:ss-example
```

Harness 启动时会下载并加载基础配置中的技能。`space:ss-example` 会加载该技能空间中的全部技能，并与 Skill Hub 技能组成一个 `SkillToolset`。调用时也可以临时增加技能空间：

```bash lines theme={null}
veadk harness invoke \
  --name research-agent \
  --message "整理一份研究报告" \
  --skills "space:ss-example"
```

调用级 `--skills` 在基础 Harness 配置上增加本次所需技能，不会修改 `harness.yaml`。如果任一技能无法下载、缺少有效的 `SKILL.md` 或不符合 ADK 技能格式，Harness 会终止本次加载，不会以不完整的技能集合继续运行。

## 技能目录结构

一个本地技能由独立目录构成，包含一个 `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],
)
```