技能

技能（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：

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 会在需要某个技能时按需下载并加载：

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 一致：

---
name: kb-skill
description: 查询知识库并整理答案的技能。
---

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

Deprecated：VeADK 旧本地入口

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

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

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

本地模式

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

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 会在需要时调用该工具在沙箱中执行所选技能：

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 工具将每一项标记为已完成：

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 初始化时一次性声明全部技能：

from veadk import Agent

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

参数总览