volcengine · xgtcode · Jun 23, 2026
diff --git a/docs/content/docs/framework/agent/skills.en.mdx b/docs/content/docs/framework/agent/skills.en.mdx
@@ -2,60 +2,94 @@
 title: "Skills"
 ---
 
-Skills are reusable "prompt packages" that inject specific domain knowledge, operating procedures, and scripts into an Agent. Instead of stuffing all prompts into `instruction` at once, skills use **progressive prompt loading**: the Agent loads a skill's full content only when needed, which keeps the context length under control and improves execution accuracy.
+Skills are reusable "prompt packages" that inject specific domain knowledge, operating procedures, and scripts into an Agent. For local skill loading and execution, the recommended integration is Google ADK's official `load_skill_from_dir` / `SkillToolset` path. VeADK's legacy `Agent(skills=..., skills_mode="local")` local entry point remains compatible, but is deprecated. The `skills_sandbox` and `aio_sandbox` modes keep their existing behavior.
 
-VeADK provides three skill execution modes:
+## Recommended: ADK SkillToolset
 
-| Mode | Description |
-| :- | :- |
-| `local` | Skills live in a local directory and are loaded and executed locally by the Agent. |
-| `skills_sandbox` | Skills are hosted in a cloud Skill Space and executed in a sandbox through the `execute_skills` tool. |
-| `aio_sandbox` | All-in-one sandbox mode, suitable for the AgentKit-hosted tool runtime. |
+Local skills can be loaded directly by Google ADK and passed to a VeADK Agent as a standard toolset:
 
-When `skills_mode` is not set explicitly, VeADK infers it from the runtime environment: local runs default to `local`; in the AgentKit tool runtime, it automatically selects `skills_sandbox` or `aio_sandbox` based on the tool type.
+```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])],
+)
+```
+
+On this path, skill loading, prompt injection, and tool exposure are handled by ADK. The model sees ADK's official skill tools: `list_skills`, `load_skill`, `load_skill_resource`, and `run_skill_script`. If a skill depends on `scripts/`, configure an appropriate `code_executor` explicitly on the `SkillToolset` or Agent; VeADK does not create a local code executor by default.
+
+Cloud SkillHub / SkillSpace skills can be downloaded and converted into ADK `Skill` objects first, then passed the same way:
+
+```python
+from google.adk.tools.skill_toolset import SkillToolset
+from veadk import Agent
+from veadk.skills import load_skills_from_source
+
+skills = load_skills_from_source(skill_space_id)
+agent = Agent(
+    tools=[SkillToolset(skills=skills)],
+)
+```
+
+`load_skills_from_source` fetches remote metadata, downloads the zip, extracts it safely, runs ADK validation, and fails fast when anything is invalid.
 
 ## Skill Directory Structure
 
-A local skill consists of its own directory containing a single `SKILL.md` file:
+An ADK local skill consists of its own directory containing a `SKILL.md` file. The frontmatter must include `name` and `description`, and the directory name must match `name`:
 
 <Files>
   <Folder name="skills" defaultOpen>
-    <Folder name="kb_skill" defaultOpen>
+    <Folder name="kb-skill" defaultOpen>
       <File name="SKILL.md" />
+      <Folder name="references" />
+      <Folder name="assets" />
+      <Folder name="scripts" />
     </Folder>
   </Folder>
 </Files>
 
-`SKILL.md` declares `name` and `description` in frontmatter, followed by the skill body:
-
-```markdown title="skills/kb_skill/SKILL.md"
+```markdown title="skills/kb-skill/SKILL.md"
 ---
-name: kb_skill
+name: kb-skill
+description: Query the knowledge base and compose an answer.
 ---
 
 ...body (operating steps, constraints, script descriptions, etc.)
 ```
 
-<Callout type="warn" title="Naming requirement">
-The `name` in `SKILL.md` must match the directory name.
-</Callout>
+## Deprecated: VeADK Legacy Local Entry
+
+`Agent(skills=..., skills_mode="local")` keeps its legacy behavior, but this local entry point is deprecated. Whether `skills` contains local directories or remote skill sources, once the final mode is `local`, VeADK uses the legacy local loading path: it loads skill metadata, writes the skill list into `instruction`, and mounts the legacy `SkillsToolset`.
+
+The `skills` parameter still supports three skill execution modes. Only the legacy `local` loading and execution path is deprecated:
+
+| Mode | Description |
+| :- | :- |
+| `local` | Deprecated. Skills are loaded by VeADK's legacy `skills_tool` plus file/Shell helper tools; migrate to ADK `SkillToolset` for local execution. |
+| `skills_sandbox` | Skills are hosted in a cloud Skill Space and executed in a sandbox through the `execute_skills` tool. |
+| `aio_sandbox` | All-in-one sandbox mode, suitable for the AgentKit-hosted tool runtime. |
+
+When `skills_mode` is not set explicitly, VeADK infers it from the runtime environment: local runs default to `local`; in the AgentKit tool runtime, it automatically selects `skills_sandbox` or `aio_sandbox` based on the tool type.
 
-## Local Mode
+### Local Mode
 
-In `local` mode, pass the skill directory path to `skills` and set `skills_mode` to `local`:
+In `local` mode, pass the skills root directory path to `skills` and set `skills_mode` to `local`:
 
 ```python
 from veadk import Agent
 
 agent = Agent(
-    skills=["/abs/path/to/skills/kb_skill"],
+    skills=["/abs/path/to/skills"],
     skills_mode="local",
 )
 ```
 
 During initialization, the Agent loads each skill's metadata (`name` and `description`) and injects it into the system prompt, guiding the model to invoke the corresponding skill at the right time. In local mode, VeADK also automatically mounts a set of supporting tools (read/write files, edit files, run shell commands, register skills, etc.) for the Agent to use when executing a skill.
 
-## Sandbox Mode
+### Sandbox Mode
 
 In `skills_sandbox` mode, skills are hosted in a cloud Skill Space. Pass the cloud skill space identifier to `skills` and add the `execute_skills` tool; the Agent invokes that tool to execute the chosen skill in the sandbox when needed:
 
@@ -65,27 +99,28 @@ from veadk.tools.builtin_tools.execute_skills import execute_skills
 
 agent = Agent(
     skills=[skill_space_id],
+    skills_mode="skills_sandbox",
     tools=[execute_skills],
 )
 ```
 
-## Skill Checklist
+### Skill Checklist
 
 A skill can carry a checklist in its definition to constrain the Agent to complete the task step by step. When enabled, the Agent must complete each checklist item while executing the skill, and mark each item as done through the `update_check_list` tool:
 
 ```python
 from veadk import Agent
 
 agent = Agent(
-    skills=["/abs/path/to/skills/kb_skill"],
+    skills=["/abs/path/to/skills"],
     skills_mode="local",
     enable_skills_checklist=True,
 )
 ```
 
 When a skill defines a checklist, VeADK automatically initializes the state of all checklist items when the skill is invoked, and prompts the model in the system prompt to complete them one by one.
 
-## Dynamically Loading Skills
+### Dynamically Loading Skills
 
 With `enable_dynamic_load_skills=True`, new skills can be discovered and loaded at runtime, without declaring all skills up front at Agent initialization:
 
@@ -102,7 +137,7 @@ agent = Agent(
 
 | Parameter | Type | Description |
 | :- | :- | :- |
-| `skills` | `list[str]` | The skill list; each element is a local skill directory path or a cloud skill space identifier. |
-| `skills_mode` | `"local" \| "skills_sandbox" \| "aio_sandbox"` | Skill execution mode; inferred automatically when omitted. |
-| `enable_skills_checklist` | `bool` | Whether to enable the skill checklist; defaults to `False`. |
-| `enable_dynamic_load_skills` | `bool` | Whether to enable dynamic loading of skills; defaults to `False`. |
+| `skills` | `list[str]` | Skill list; each item is a local skills root path or a cloud skill-space identifier. The legacy local loading path is deprecated when `skills_mode="local"`. |
+| `skills_mode` | `"local" \| "skills_sandbox" \| "aio_sandbox"` | Skill execution mode; inferred automatically when omitted. The legacy `local` path is deprecated, while `skills_sandbox` / `aio_sandbox` keep their existing behavior. |
+| `enable_skills_checklist` | `bool` | Whether to enable the legacy skill checklist; defaults to `False`. |
+| `enable_dynamic_load_skills` | `bool` | Whether to enable dynamic loading for legacy skills; defaults to `False`. |
diff --git a/docs/content/docs/framework/agent/skills.mdx b/docs/content/docs/framework/agent/skills.mdx
@@ -2,60 +2,94 @@
 title: "技能"
 ---
 
-技能（Skills）是一种可复用的「提示词包」，用于为 Agent 注入特定的领域知识、操作流程与脚本。与一次性把所有提示词塞入 `instruction` 不同，技能采用**渐进式加载（progressive prompt loading）**：Agent 仅在需要时才加载某个技能的完整内容，从而控制上下文长度、提升执行准确性。
+技能（Skills）是一种可复用的「提示词包」，用于为 Agent 注入特定的领域知识、操作流程与脚本。本地技能加载/执行场景推荐使用 Google ADK 官方的 `load_skill_from_dir` / `SkillToolset` 方式接入；VeADK 旧的 `Agent(skills=..., skills_mode="local")` 本地入口仍保持兼容，但已标记为 deprecated。`skills_sandbox` 与 `aio_sandbox` 模式仍按原方式使用。
 
-VeADK 提供三种技能运行模式：
+## 推荐：ADK SkillToolset
 
-| 模式 | 说明 |
-| :- | :- |
-| `local` | 技能位于本地目录，直接由 Agent 加载并在本地执行。 |
-| `skills_sandbox` | 技能托管在云端技能空间（Skill Space），通过 `execute_skills` 工具在沙箱中执行。 |
-| `aio_sandbox` | All-in-one 沙箱模式，适用于 AgentKit 托管的工具运行时。 |
+本地技能可直接通过 Google ADK 加载，并作为标准工具集传给 VeADK Agent：
 
-未显式设置 `skills_mode` 时，VeADK 会根据运行环境自动推断：本地运行默认为 `local`；在 AgentKit 工具运行时中，会根据工具类型自动选择 `skills_sandbox` 或 `aio_sandbox`。
+```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 技能可先下载并转换为 ADK `Skill`，再按同样方式传入：
+
+```python
+from google.adk.tools.skill_toolset import SkillToolset
+from veadk import Agent
+from veadk.skills import load_skills_from_source
+
+skills = load_skills_from_source(skill_space_id)
+agent = Agent(
+    tools=[SkillToolset(skills=skills)],
+)
+```
+
+`load_skills_from_source` 会在调用时拉取远端 metadata、下载 zip、安全解压、执行 ADK 校验，并在失败时立即报错。
 
 ## 技能目录结构
 
-一个本地技能由独立目录构成，目录中包含一个 `SKILL.md` 文件：
+一个 ADK 本地技能由独立目录构成，目录中包含一个 `SKILL.md` 文件。`SKILL.md` 必须包含 `name` 与 `description` frontmatter，且目录名必须与 `name` 一致：
 
 <Files>
   <Folder name="skills" defaultOpen>
-    <Folder name="kb_skill" defaultOpen>
+    <Folder name="kb-skill" defaultOpen>
       <File name="SKILL.md" />
+      <Folder name="references" />
+      <Folder name="assets" />
+      <Folder name="scripts" />
     </Folder>
   </Folder>
 </Files>
 
-`SKILL.md` 使用 frontmatter 声明 `name` 与 `description`，其后为技能正文：
-
-```markdown title="skills/kb_skill/SKILL.md"
+```markdown title="skills/kb-skill/SKILL.md"
 ---
-name: kb_skill
+name: kb-skill
+description: 查询知识库并整理答案的技能。
 ---
 
 ...正文部分（操作步骤、约束、脚本说明等）
 ```
 
-<Callout type="warn" title="命名要求">
-`SKILL.md` 中的 `name` 必须与所在目录名保持一致。
-</Callout>
+## 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`：
+在 `local` 模式下，向 `skills` 传入技能根目录的路径，并将 `skills_mode` 设置为 `local`：
 
 ```python
 from veadk import Agent
 
 agent = Agent(
-    skills=["/abs/path/to/skills/kb_skill"],
+    skills=["/abs/path/to/skills"],
     skills_mode="local",
 )
 ```
 
 Agent 在初始化时会加载技能元信息（`name` 与 `description`）并将其注入系统提示词，引导模型在合适的时机调用对应技能。本地模式下，VeADK 还会自动挂载一组配套工具（读写文件、编辑文件、执行 Shell 命令、注册技能等），供 Agent 在执行技能时使用。
 
-## 沙箱模式
+### 沙箱模式
 
 在 `skills_sandbox` 模式下，技能托管在云端技能空间。向 `skills` 传入云端技能空间标识，并引入 `execute_skills` 工具，Agent 会在需要时调用该工具在沙箱中执行所选技能：
 
@@ -65,27 +99,28 @@ 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）
 
 技能可在其定义中携带一份检查清单（checklist），用于约束 Agent 按步骤完成任务。开启后，Agent 在执行技能时需逐项完成检查项，并通过 `update_check_list` 工具将每一项标记为已完成：
 
 ```python
 from veadk import Agent
 
 agent = Agent(
-    skills=["/abs/path/to/skills/kb_skill"],
+    skills=["/abs/path/to/skills"],
     skills_mode="local",
     enable_skills_checklist=True,
 )
 ```
 
 当某个技能定义了 checklist 时，VeADK 会在该技能被调用时自动初始化所有检查项的状态，并在系统提示词中提示模型逐项完成。
 
-## 动态加载技能
+### 动态加载技能
 
 通过 `enable_dynamic_load_skills=True`，可在运行时动态发现并加载新的技能，而无需在 Agent 初始化时一次性声明全部技能：
 
@@ -102,7 +137,7 @@ agent = Agent(
 
 | 参数 | 类型 | 说明 |
 | :- | :- | :- |
-| `skills` | `list[str]` | 技能列表，元素为本地技能目录路径或云端技能空间标识。 |
-| `skills_mode` | `"local" \| "skills_sandbox" \| "aio_sandbox"` | 技能运行模式，缺省时自动推断。 |
-| `enable_skills_checklist` | `bool` | 是否启用技能检查清单，默认 `False`。 |
-| `enable_dynamic_load_skills` | `bool` | 是否启用技能的动态加载，默认 `False`。 |
+| `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`。 |