Agent Zero skills_tool 完全指南search、list、load、read_file 四动作驱动的技能调度体系【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent ZeroAGI 开源框架为智能体内置了skills_tool工具用于按需发现、加载并执行基于SKILL.md标准的技能。本文以 prompts/agent.system.tool.skills.md 中定义的调用协议为核心骨架结合 tools/skills_tool.py 与 helpers/skills.py 的源码实现完整讲解search、list、load、read_file四个动作的语义、参数与底层行为并给出可直接复制的调用示例。读完本文你将掌握 Agent Zero 中何时搜、何时列、何时载、如何读的完整技能调度心智模型并能理解技能的目录发现、frontmatter 解析、评分排序与上下文加载限制等底层机制。一、skills_tool 是什么Agent Zero 的技能按需加载机制skills_tool是 Agent Zero 的代理Agent运行时内置工具负责管理基于SKILL.md标准的技能Anthropic 开放技能规范。其设计哲学是按需加载、按相关性启用技能不是像普通工具那样常驻在工具清单里而是在任务需要时才被检索、加载进对话上下文。从 tools/skills_tool.py 的类注释可以看到它的定位Manage and use SKILL.md-based Skills (Anthropic open standard). Actions (tool_args.action): - list - search (query) - load (skill_name, or /command) - read_file (skill_name, file_path)四个动作、四个通用参数构成了整个技能体系的对外接口动作 action作用常用参数search按关键词或触发短语检索候选技能querylist列出当前 Agent 可见的全部技能与斜杠命令无load将某个技能的完整指令追加进对话历史skill_name或用skill_name/command读取斜杠命令定义read_file打开已加载技能目录内的某个文件skill_namefile_pathAgent Zero 的核心提示词 prompts/agent.system.tool.skills.md 对使用原则作了硬性约束use skills only when relevant只在相关时才使用技能并且规定了一个重要流程规则if the user says find/search a skill, callsearchbeforeloadeven when the likely skill name seems obvious 当用户要求查找/搜索一个技能时即使技能名看起来显而易见也必须先调用search再load二、actionsearch按触发短语发现技能search是技能调度的起点。它通过关键词或触发短语从当前 Agent 可用的技能集合中找出候选而不是直接给出完整指令。调用格式如下{ thoughts: [The users request sounds like a skill trigger phrase, so I should search first.], headline: Searching for relevant skill, tool_name: skills_tool, tool_args: { action: search, query: set up a0 cli connector } }这是 prompts/agent.system.tool.skills.md 中给出的标准示例当用户请求听起来像某个技能的触发短语时先搜索而不是直接猜技能名。底层评分算法search的实际执行委托给 helpers/skills.py 中的search_skills(query, limit25, agentNone)函数搜索上限 25 条。从源码可以看到它并非简单的字符串包含匹配而是对技能的名称、描述、标签、触发短语进行加权打分查询与技能名完全相等10 分查询与某个触发短语完全相等9 分查询包含在技能名中6 分查询包含在技能描述中4 分查询包含在某个标签中3 分查询与触发短语存在互相包含关系8 分分词≥4 字符或含数字命中技能名每个词 3 分长词≥6 字符或含数字命中标签/触发短语1 / 4 分最终按分数降序、同名按字母序排序后截取前 25 条。search的返回结果是带描述的技能列表描述超过 200 字符会截断并在末尾附带提示Tip: use skills_tool actionload skill_name to load full instructions.三、actionlist浏览技能目录与斜杠命令list用于获取更宽的目录视图适合在不确定有哪些技能可用、或需要整体盘点时使用。它的返回内容分两部分技能列表按名称字母序稳定排序每条包含名称、版本vX.Y.Z、标签tags和截断到 200 字符的描述斜杠命令列表来自_commands插件的生效命令每条包含/名称、参数提示与描述。如果当前没有任何技能也没有斜杠命令返回No skills or slash commands found.从源码看list走的是 helpers/skills.py 的list_skills(agent, include_contentFalse)与list_slash_commands(agent)其中斜杠命令还会过滤掉frontmatter_extra.webui_hidden为真的命令即对 WebUI 选择器隐藏的命令不显示。技能的发现路径get_skill_roots()揭示了 Agent Zero 的技能来源按优先级排序同名去重时靠前的优先仓库根skills/内置技能例如 skills/a0-development/SKILL.md用户目录usr/skills/项目级usr/projects/*/.a0proj/skills与usr/projects/*/.a0proj/agents/*/skillsAgent 级usr/agents/*/skills、agents/*/skills插件级plugins/*/skills、usr/plugins/*/skills、plugins/*/agents/*/skills、usr/plugins/*/agents/*/skills每个技能根目录下通过递归查找SKILL.md文件来发现技能隐藏目录以.开头的路径会被忽略。四、actionload把技能指令写入对话上下文load是整个体系的核心动作。它会把一个技能的完整指令frontmatter 元数据 正文 文件树格式化为可读文本追加到 Agent 的对话历史中之后 Agent 才能遵循该技能执行。调用示例{ tool_name: skills_tool, tool_args: { action: load, skill_name: a0-development } }加载后返回的内容结构从load_skill_for_agent()的源码可以看到加载结果的排版为Skill: a0-development Path: skills/a0-development Version: 1.1.0 Author: Agent Zero Team License: ... Tags: development, framework, agent-zero, ... Triggers: extend agent zero, agent zero development, ... Description: 技能描述 Content (SKILL.md body): SKILL.md 正文 Files (use skills_tool actionread_file to open): 技能目录的文件树深度最多 10 层幂等保护避免重复加载_load()中有一层已在可见上下文中的检查_visible_skill_loaded如果该技能指令已经存在于 Agent 的输出历史中则不再重复注入全文而是返回Skill xxx is already loaded in visible chat history.并附上already_loaded: True的元数据避免上下文被同一份长指令反复撑大。加载斜杠命令skill_name/commandload还支持一种特殊用法当skill_name以/开头时工具不加载技能而是读取一个生效的斜杠命令定义不触发执行。例如skill_name/command会返回Slash command: /visible Description: Visible command. Arguments: text Type: text Scope: Project Definition: Template {text}该格式化逻辑位于 helpers/skills.py 的format_slash_command()包含名称、描述、参数提示、命令类型、作用域标签与正文正文超过 24000 字符截断。测试 tests/test_skills_runtime.py 中的test_slash_commands_use_agent_scope_and_hide_picker_hidden验证了斜杠命令按 Agent 项目作用域查找、且对 picker 隐藏的命令不可见的行为。已加载技能的管理上限Agent 会话内维护一个已加载技能名列表存储于 context 的loaded_skills数据键中兼容旧版agent.data[loaded_skills]。默认上限MAX_ACTIVE_SKILLS 20helpers/skills.py 第 21 行测试test_active_skills_cap_is_twenty对此做了断言该上限可通过_skills插件的max_active_skills配置调高test_skills_config_can_raise_active_cap_above_default验证了配置为 25 时生效。当加载超过上限时只保留最近加载的技能名。五、actionread_file安全读取技能目录内文件很多技能如 skills/a0-development/SKILL.md本体是瘦指令真正的详细参考资料放在references/等子目录中通过read_file按需打开。调用要求read_filerequires bothskill_nameandfile_path; load the skill first, then readSKILL.mdor the named relative file即必须先load技能再读取其目录内的文件。示例来自 a0-development 技能自身的用法说明{tool_name: skills_tool:read_file, tool_args: {skill_name: a0-development, file_path: references/architecture-runtime.md}}三重安全检查_read_file()在源码中实现了严格的安全边界技能必须存在find_skill()找不到时直接报错路径必须限定在技能目录内file_path相对于技能根目录解析绝对路径则直接使用随后通过resolved.relative_to(skill_root)校验任何越界尝试如../逃逸或指向/etc/passwd都会返回Error: file_path must stay inside the skill directory.内容截断保护文件内容超过 24000 字符时截断并追加[truncated]标记防止超大文件一次性灌入上下文。返回格式为Skill file: skill.name/相对路径加文件内容方便 Agent 明确知道内容来源。六、Agent 何时该用 skills_tool配套提示词协议skills_tool并不是孤立工具它与一组系统提示词协同工作定义了 Agent 的技能使用纪律prompts/agent.system.skills.md 给出总原则当用户措辞听起来像某个技能的任务/触发短语/关键词时用search需要更宽目录视图时用list遵循某个技能前必须先load。并特别强调已加载的技能可能记录了一些不在常驻工具列表中的 beta/专用工具只有在加载该技能之后才允许使用它们——这是防止 Agent 幻觉调用未注册工具的关键约束prompts/agent.system.skills.relevant.md 说明上下文中的 relevant skills 区块是系统按词法搜索含触发短语匹配出来的候选如果当前请求依赖其中某个技能必须先load再遵循prompts/agent.system.skills.loaded.md 说明上下文中的 loaded skills 区块记录了已通过skills_tool显式加载的技能。从源码的上下文数据键helpers/skills.py 第 22-27 行还可以看到更精细的会话级控制skills_chat_active当前对话激活的技能、skills_chat_disabled当前对话禁用的技能、skills_chat_visible当前对话可见的技能配合activate_chat_skill/deactivate_chat_skill/hide_chat_skill/show_chat_skill等函数实现了作用域默认 对话级覆盖的双层技能开关体系。七、SKILL.md 规范技能如何被识别与校验load能工作前提是技能目录里存在符合规范的SKILL.md。helpers/skills.py 的解析流程skill_from_markdown→split_frontmatter→validate_skill对技能文件有明确要求YAML frontmatter 必须位于文件顶部缺失、未闭合或前置非空文本都会导致技能被跳过并输出skill xxx skipped: invalid frontmatter警告必填字段name1-64 字符仅小写字母、数字、连字符不能以连字符开头/结尾或含连续--和description≤1024 字符可选字段version、author、license、tags、triggers/trigger_patterns/trigger三者互为别名、allowed_tools别名allowed-tools/tools、compatibility≤500 字符、metadata兼容多种社区写法description 也可用when_to_use/summary别名。以仓库内置技能 skills/a0-development/SKILL.md 为例其 frontmatter 同时声明了version: 1.1.0、author: Agent Zero Team、12 个tags和 18 条trigger_patterns正文则是参考地图 工作流程 交接约定的经典瘦技能结构——这类技能正是read_file动作的典型消费场景。八、端到端调用示例一次完整的技能调度会话把上述动作串起来一次典型流程如下第 1 步search用户说帮我把 a0 cli connector 配置起来。Agent 判断这是技能触发短语先调用search{ tool_name: skills_tool, tool_args: { action: search, query: set up a0 cli connector } }返回候选技能及其描述此处对应仓库中的 a0-contribute-plugin、a0-create-plugin、a0-manage-plugin、a0-debug-plugin、a0-review-plugin、a0-development、a0-plugin-router、build-skill 等技能集合中的匹配项。第 2 步load命中后加载完整指令{ tool_name: skills_tool, tool_args: { action: load, skill_name: a0-plugin-router } }技能全文含路径、元数据、正文、文件树进入对话上下文。第 3 步read_file技能正文要求先读参考文件再打开其内部文档{ tool_name: skills_tool, tool_args: { action: read_file, skill_name: a0-plugin-router, file_path: references/plugin-lifecycle.md } }第 4 步执行按技能指令使用code_execution_tool或其他工具执行技能引用的脚本/文件脚本执行由 code_execution 工具负责skills_tool 本身不执行代码。第 5 步按需 reload若后续上下文中技能指令已被挤出上下文窗口再次load同一技能即可重新注入此时already_loaded检查不会误判因为内容已不在可见历史中。九、错误处理与健壮性tools/skills_tool.py 对每个动作都有防御性校验常见错误信息一览场景返回缺少/非法actionError: missing/invalid action. Supported actions: list, search, load, read_file.search缺queryError: query is required for actionsearch.search无结果No skills matched query: xxxload缺skill_nameError: skill_name is required for actionload.load找不到技能Error: skill not found: xxx. Try skills_tool actionlist or actionsearch.load找不到斜杠命令Error: slash command not found: xxx. Try skills_tool actionlist.read_file越界Error: file_path must stay inside the skill directory.内部异常Error in skills_tool: 异常信息保证工具不会让 Agent 主循环崩溃此外动作名支持归一化处理转小写、-转_技能名会剥离**xxx**这类 markdown 加粗包裹——这意味着即使 LLM 在生成参数时带上了格式符号也能被正确解析。十、总结skills_tool是 Agent Zero 技能体系的调度中枢search用加权评分完成候选发现list提供目录总览load把技能指令安全注入上下文含斜杠命令读取与 20 个技能的上限管理read_file在严格的目录边界内按需打开技能附属文件。整个体系以 prompts/agent.system.tool.skills.md 的协议为纲、以 tools/skills_tool.py 和 helpers/skills.py 为实现并通过 tests/test_skills_runtime.py 等测试用例持续守护行为契约。理解这套机制你就能在扩展 Agent Zero 时正确设计瘦技能 参考文件的目录结构也能更准确地预测 Agent 在复杂任务中检索与执行技能的行为。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考