Agent Zero 技能系统完全指南SKILL.md 的搜索、加载与应用机制【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent Zero 通过 SKILL.md 文件格式Anthropic 开放标准将可复用的操作流程封装成技能供 AI 代理在对话中按需检索、加载和执行。本文基于 prompts/agent.system.skills.md 及其配套的系统提示词、skills_tool 工具源码与 helpers/skills.py 实现完整讲解 Agent Zero 的技能发现、搜索、加载、读取文件、配置管理及底层原理让读者掌握如何在 Agent Zero 中高效利用技能系统完成复杂任务。技能系统的定位让 Agent 按需获得领域能力在 Agent Zero 中skills_tool是代理Agent与技能目录之间的唯一桥梁。技能本质上是一份带有 YAML frontmatter 元数据的 Markdown 文件SKILL.md它可以把某类任务的完整执行流程——触发条件、使用时机、操作步骤、参考文件——固化下来供代理在对话中随时调用。技能与常驻工具always-on tools的关键区别在于技能可能文档化一些仅在特定场景才需要的 beta/专用工具代理必须在加载该技能之后才能使用这些工具参见 prompts/agent.system.skills.md 第 6 行。这一设计直接源于 prompts/agent.system.tool.skills.md 中定义的代理行为契约use skills only when relevant仅在相关时使用技能。技能系统的价值在于按需加载——代理不会在每一轮对话中都携带全部技能而是在用户请求与某个技能的触发词trigger phrase或关键词匹配时才去搜索并加载对应技能从而在保持上下文精简的同时获得特定领域的完整操作指引。skills_tool 的四种动作搜索 → 列表 → 加载 → 读文件prompts/agent.system.skills.md 为代理定义了完整的使用流程其核心是四种动作。下表综合了该文档与 tools/skills_tool.py 中的实现第 118-136 行execute方法动作 (action)常用参数用途底层实现searchquery当用户表述听起来像某个技能的触发词/关键词时先搜索候选技能helpers/skills.py 中search_skills()做词法打分排序list无查看更完整的技能目录视图含斜杠命令list_skills()list_slash_commands()loadskill_name将某个技能的完整指令追加到聊天历史load_skill_for_agent()格式化完整技能内容read_fileskill_name,file_path读取已加载技能目录内的一个文件_read_file()带路径越界防护search先用关键词找出候选技能当用户的话语听起来像某个任务、触发短语或与技能关键词匹配时应该先执行search再决定是否加载。如果用户明确要求查找/搜索某个技能即使代理觉得技能名称显而易见也必须先search再load见 prompts/agent.system.tool.skills.md 第 10 行。这一约束对应 tools/skills_tool.py 中_search()第 181-204 行query必填无查询时返回错误命中上限为 25 个技能。{ 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 的 JSON 演示。从源码看helpers/skills.py 的search_skills()第 589-644 行执行的是加权词法打分而非语义搜索查询串会先被拆分成词元过滤掉长度小于 4 的短词然后对每个候选技能的name、description、tags、triggers逐项加分——精确匹配技能名加 10 分、精确匹配触发词加 9 分、名称包含查询词加 6 分、描述包含加 4 分、触发词部分匹配加 8 分最后按分数降序、名称升序排列。这意味着技能的描述与触发词写得好不好直接决定了它能否被搜索到。list获得目录全貌当需要更宽泛的目录视图时使用list。它不需要任何参数缺失或空action默认就是list见 tools/skills_tool.py 第 27-37 行的_normalize_action与第 30 行注释。从_list()第 142-179 行的实现看输出包含两部分技能列表按名称排序每条显示名称、v版本号、tags若有和截断到 200 字符的描述斜杠命令列表显示当前项目所有在 UI 选择器中可见的/命令及其参数提示与描述。输出末尾还会附上一句提示Tip: use skills_tool actionsearch for skills or actionload skill_name/name to read a slash command.tools/skills_tool.py 第 176-178 行。load把完整指令追加进聊天历史加载技能是使用技能的前置条件。load会把该技能的完整正文追加到聊天历史中形成带skill_instructions元数据的普通 tool-result 消息见 tools/skills_tool.py.dox.md 第 29 行。从_load()第 206-282 行可以看到几个关键行为skill_name必填以/开头的名称会被当作斜杠命令处理——find_slash_command()查找后经format_slash_command()渲染出命令定义包含描述、参数、类型、作用域与正文但不会执行命令也不会记入已加载技能账本tools/skills_tool.py.dox.md 第 33 行普通技能先find_skill()校验存在再load_skill_for_agent()格式化完整内容名称、路径、版本/作者/许可/兼容性/标签/允许工具/触发词等元数据、描述、正文、文件树加载成功后通过add_loaded_skill_name()记入聊天级上下文数据受MAX_ACTIVE_SKILLS限制见下文配置节去重优化如果同名技能的内容已经可见于聊天历史则不再重复注入正文而是返回already loaded提示_visible_skill_loaded()第 284-293 行。{ tool_name: skills_tool, tool_args: { action: load, skill_name: a0-contribute-plugin } }以仓库自带的技能 skills/a0-contribute-plugin/SKILL.md 为例其 frontmatter 声明了name、description、version、tags与trigger_patterns如 contribute plugin、publish plugin。加载后代理即可按照正文中的 6 个步骤引导用户发布插件到社区 Plugin Index。read_file读取技能目录内的文件加载技能后技能正文通常会附带一个文件树见 helpers/skills.py 的_get_skill_files()第 565-587 行使用 conf/skill.default.gitignore 过滤无关文件。当需要查看技能引用的脚本、配置或文档时使用read_file它必须同时提供skill_name和file_pathprompts/agent.system.tool.skills.md 第 11 行。从 tools/skills_tool.py 的_read_file()第 295-330 行看其安全设计值得注意相对路径会基于技能根目录解析随后通过resolved.relative_to(skill_root)校验——任何试图逃出技能目录的路径如../都会被拒绝返回 file_path must stay inside the skill directory。文件内容超过 24000 字符时会被截断并追加[truncated]标记。技能的存储位置与发现机制Agent Zero 的技能不是单一目录而是分布式的。从 helpers/skills.py 的get_skill_roots()第 68-97 行可见技能根目录按作用域分为两类全局扫描路径无 agent 上下文时包括skills/仓库内置技能usr/skills/用户级技能usr/projects/*/.a0proj/skills/与usr/projects/*/.a0proj/agents/*/skills/项目及项目内代理usr/agents/*/skills/用户代理agents/*/skills/内置代理plugins/*/skills/与usr/plugins/*/skills/插件技能plugins/*/agents/*/skills/与usr/plugins/*/agents/*/skills/插件内代理代理可用路径则通过subagents.get_paths(agent, skills)获得意味着每个代理看到的技能集合取决于其 profile 配置。发现过程discover_skill_md_files()第 104-125 行是递归遍历根目录下所有SKILL.md文件并忽略隐藏路径以.开头的目录/文件。仓库内置技能位于 skills/例如a0-create-plugin、a0-debug-plugin、a0-manage-plugin、a0-review-plugin、a0-development、scheduled-tasks等另有大量技能内嵌于插件目录如plugins/_a0_connector/skills/、plugins/_browser/skills/等。代理级别的技能去重遵循根目录优先级先到先得list_skills()第 368-398 行对每个 agent 按标准化名称去重更靠前的根目录作用域更高优先保留。这也解释了为什么同名技能在不同代理/项目中会解析到不同路径——这与 prompts/agent.system.skills.relevant.md 描述的按当前请求的词法搜索匹配技能机制配合形成多级作用域下的技能解析链路。SKILL.md 格式规范frontmatter 与校验规则Agent Zero 严格遵循 Anthropic 的 SKILL.md 开放标准。从 helpers/skills.py 的解析器看split_frontmatter()第 153-190 行要求YAML frontmatter 必须位于文件顶部允许前导空行且必须被---围栏正确闭合否则该技能会被跳过并在终端输出警告_warn_skill_skipped()第 283-297 行。解析时优先使用 PyYAML不可用时回退到内置的极简 YAML 子集解析器_parse_frontmatter_fallback()第 193-228 行仅支持key: value与- item列表。skill_from_markdown()第 299-365 行提取的核心字段及别名如下字段别名兼容说明nameskill技能名必填descriptionwhen_to_use,summary技能描述必填triggerstrigger_patterns,trigger,activation触发短语用于搜索匹配tagstag分类标签allowed-toolsallowed_tools,tools允许使用的工具白名单version/author/license/compatibility—元信息validate_skill()第 650-677 行是硬性校验name必填、长度 1-64、只能是小写字母/数字/连字符且不能以连字符开头结尾、不能含连续连字符description必填且不超过 1024 字符compatibility不超过 500 字符。任何校验失败都会导致技能被排除出目录。仓库技能 skills/a0-contribute-plugin/SKILL.md 是符合规范的完整示例。已加载技能的上下文管理prompts/agent.system.skills.loaded.md 指出已加载技能the following skills were explicitly loaded via skills_tool会以特殊元数据形式出现在代理上下文中。从源码看加载账本loaded-skill ledger存储在聊天级上下文数据CONTEXT_DATA_NAME_LOADED_SKILLS见 helpers/skills.py 第 24-25 行并有从旧版 agent data 自动迁移的兼容逻辑get_loaded_skill_names()第 959-979 行。关键常量是MAX_ACTIVE_SKILLS 20第 21 行add_loaded_skill_name()第 1001-1013 行在追加新技能时会裁剪到最近 20 个。对代理而言这意味着如果已加载技能的指令不再处于上下文中需要重新loadprompts/agent.system.tool.skills.md 第 13 行。同理重复加载同一技能时若其正文仍可见于聊天历史工具会返回already_loaded标记而不重复注入tools/skills_tool.py 第 262-276 行从而避免上下文膨胀。技能可见性与激活配置_skills 插件技能的加载与可见性管理由内置插件_skills承担。其清单 plugins/_skills/plugin.yaml 声明always_enabled: true、per_project_config: true并只挂接 agent 级设置面板。默认配置位于 plugins/_skills/default_config.yamlmax_active_skills: 20 active_skills: [] hidden_skills: []三个配置项分别对应 helpers/skills.py 中的get_max_active_skills()第 710-726 行、get_scope_active_skills()第 828-845 行与get_scope_hidden_skills()第 848-862 行。从 plugins/_skills/README.md 的说明可归纳其行为active_skills将选中的技能加载进当前聊天历史使用与skills_tool相同的元数据形状hidden_skills把嘈杂的技能从模型可见的目录、搜索与加载访问中隐藏隐藏项存为控制数据不会注入提示词隐藏技能的路径以归一化的/a0/...形式存储保证开发环境与 Docker 布局之间的可移植性plugins/_skills/README.md 第 27 行支持全局与项目级作用域配置per_project_config: true但不支持代理级变体若配置的隐藏技能在当前代理作用域内不可见会静默跳过而非破坏目录构建。此外聊天级还有一套运行时覆盖机制activate_chat_skill/deactivate_chat_skill/hide_chat_skill/show_chat_skillhelpers/skills.py 第 1039-1226 行允许在单个对话内动态启用、禁用、隐藏或恢复技能最终通过_merge_active_skill_entries()第 1377-1401 行合并作用域默认配置与聊天动态覆盖并受max_active_skills上限约束——尝试激活超过上限的技能会抛出 You can activate at most N skills 错误第 1078-1081 行。系统提示中的技能上下文模板{{skills}}占位符会在运行时被真实的技能列表替换用于三种不同场景prompts/agent.system.skills.md主技能指令定义 search/list/load 的使用规则并列出所有可用技能prompts/agent.system.skills.relevant.md列出与当前请求词法匹配的相关技能含触发短语提示代理如果当前请求依赖其中之一先load再遵循同时说明远程工具桩remote tool stubs可自包含处理常规任务只有复杂远程工作流才需要加载对应远程技能prompts/agent.system.skills.loaded.md记录已通过skills_tool显式加载的技能。这三个模板分别对应全量目录、相关候选、已加载集合三个信息层级共同构成代理对技能空间的分层认知。端到端工作流从用户请求到技能执行综合 prompts/agent.system.skills.md 与 prompts/agent.system.tool.skills.md一次完整的技能使用流程如下识别触发用户请求听起来像任务/触发短语/关键词匹配搜索候选调用skills_tool actionsearch query关键词由 helpers/skills.py 的词法打分引擎返回最多 25 个候选若需全貌则actionlist加载技能对选中的skill_name调用actionload完整正文元数据 指令 文件树追加进聊天历史读取素材如需技能目录内文件用actionread_file skill_name名 file_path相对路径路径越界会被拒绝执行指令遵循技能正文用其他工具代码执行、浏览器等操作其引用的文件或脚本——只有加载技能后才能使用其文档化的专用/beta 工具上下文维护若指令不在上下文中则重新load系统会通过skill_instructions元数据与已加载账本保证重复加载不膨胀上下文。以仓库自带技能为例当用户说帮我发布插件时trigger_patterns中的 contribute plugin / publish plugin 会命中搜索代理加载 skills/a0-contribute-plugin/SKILL.md随后按正文 6 步引导询问自动化偏好 → 准备 GitHub 仓库 → 选择索引名 → 创建 index.yaml → CI 预校验 → 提交 PR。相关实现与验证可进一步阅读 tools/skills_tool.py、helpers/skills.py、plugins/_skills/README.md 及测试 tests/test_skills_catalog_api.py、tests/test_skills_runtime.py、tests/test_skills_scan.py、tests/test_skills_cli.py。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考