> ## 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.

# 技能

技能是可复用的提示词包，用于为智能体提供特定领域的知识、操作流程和脚本。VeADK 1.0.0 会先加载技能的名称与说明，并在需要使用技能时再读取完整内容，以控制上下文长度。

VeADK 1.0.0 支持三种技能运行模式：

| 模式 | 说明 |
| - | - |
| `local` | 从本地目录加载技能，并在本地执行。 |
| `skills_sandbox` | 从云端技能空间加载技能，通过 `execute_skills` 工具在沙箱中执行。 |
| `aio_sandbox` | 在 AgentKit All-in-one 工具运行时中执行技能。 |

未设置 `skills_mode` 时，VeADK 会根据运行环境选择模式：本地运行使用 `local`；AgentKit 工具运行时根据工具类型使用 `skills_sandbox` 或 `aio_sandbox`。

## 技能目录

`skills` 中的本地路径应指向技能根目录。根目录下的每个子目录代表一个技能，并包含 `SKILL.md`：

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

`SKILL.md` 的 frontmatter 必须提供 `name` 与 `description`，且 `name` 应与所在目录名一致：

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

按照下列步骤查询知识库并组织回答……
```

## 使用本地技能

```python lines theme={null}
from veadk import Agent

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

本地模式会把技能元信息加入系统提示词，并提供读取、编辑与执行技能资源所需的配套工具。运行技能脚本会访问本地文件和 Shell 环境，因此仅应加载可信的技能目录。

## 使用云端技能空间

将技能空间标识传给 `skills`，显式选择 `skills_sandbox`，并添加 `execute_skills`：

```python lines theme={null}
import os

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

agent = Agent(
    skills=[os.environ["AGENTKIT_SKILL_SPACE_ID"]],
    skills_mode="skills_sandbox",
    tools=[execute_skills],
)
```

运行前需配置可访问该技能空间和 AgentKit 工具运行时的凭证。

## 启用技能检查清单

技能可以在定义中包含检查清单。设置 `enable_skills_checklist=True` 后，VeADK 会在技能开始执行时初始化检查项，并提示模型通过 `update_check_list` 逐项更新状态：

```python lines theme={null}
from veadk import Agent

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

## 动态加载技能

设置 `enable_dynamic_load_skills=True` 后，VeADK 会在运行期间检查并重新加载技能配置：

```python lines theme={null}
from veadk import Agent

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

## 参数

| 参数 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `skills` | `list[str]` | `[]` | 本地技能根目录或云端技能空间标识列表。 |
| `skills_mode` | `"local" \| "skills_sandbox" \| "aio_sandbox" \| None` | `None` | 技能运行模式；为 `None` 时根据运行环境选择。 |
| `enable_skills_checklist` | `bool` | `False` | 是否为包含检查清单的技能启用逐项状态跟踪。 |
| `enable_dynamic_load_skills` | `bool` | `False` | 是否在运行期间检查并重新加载技能。 |