Agent Zero Skill 构建指南：基于 SKILL.md 标准创建、审计与重构可复用技能

Agent Zero Skill 构建指南基于 SKILL.md 标准创建、审计与重构可复用技能【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读本文以 Agent Zero 仓库中的 build-skill 技能文档 为核心骨架系统讲解如何在 Agent Zero 框架中创建、改进、审计与重构 Agent 技能Skill。技能是教会 Agent 执行可重复工作流的小型目录其元数据与正文组织方式直接决定运行时的发现、检索与加载效果。读完本文你将掌握技能目录的标准结构、frontmatter 元数据规范、核心/插件作用域放置规则、编写纪律与验证流程并能结合 helpers/skills.py 源码理解技能被解析、打分与加载的底层机制。一、技能是什么让 Agent 学会可重复的工作流在 Agent Zero 中技能Skill是一个小型文件夹用于教会 Agent 一项可重复执行的工作流。它并不携带复杂程序而是通过始终可见的元数据frontmatter与精炼的正文SKILL.md body在恰当的时刻被 Agent 发现、检索并加载进上下文。构建技能的核心原则只有一句话让始终可见的元数据保持精准、让 SKILL.md 保持精简、只在任务真正需要时把详细材料下沉到 scripts / references / assets 子目录。这一原则与运行时行为直接相关——元数据参与词法发现与相关性召回而正文只在技能被加载后才进入 Agent 上下文因此常驻可见的部分必须小而准。仓库中已内置了若干遵循此标准的示例技能例如本技能自身 skills/build-skill/SKILL.md、skills/a0-development/SKILL.md以及分布在插件目录下的plugins/_browser/skills/、plugins/_a0_connector/skills/等可作为写作时的参照。二、标准目录结构Standard Shape每个技能文件夹必须与技能同名并且必须包含SKILL.md。标准形态如下skill-name/ ├── SKILL.md ├── scripts/ # 可选确定性的辅助脚本 ├── references/ # 可选仅在需要时加载的细节材料 └── assets/ # 可选输出资源或模板子目录的职责边界scripts/只放置确定性或会被反复重写的操作辅助脚本且需要为代表性脚本编写测试references/存放长篇示例、schema、策略或变体细节仅在技能加载后按需读取assets/存放输出资源或模板。从源码结构看helpers/skills.py 的get_skill_roots()会通过rglob(SKILL.md)递归发现任意深度下的技能因此子目录的层级组织是自由的但 tests/test_skills_runtime.py 中的test_renamed_skills_use_standard_frontmatter_only明确断言仓库内置技能如build-skill、scheduled-tasks、host-computer-use等的 frontmatter 仅包含标准字段且name必须与父目录名一致——这印证了目录名 技能名的硬约束。三、frontmatter 元数据规范frontmatter 应包含name、description以及可选的triggers当词法发现需要描述中无法自然容纳的短语时使用--- name: skill-name description: What the skill does and when to use it. triggers: - user phrase that should surface this skill ---以本技能自身的 frontmatter 为真实范例--- name: build-skill description: Build or improve Agent Zero skills following the official SKILL.md standard. Use when the user asks to create, rename, move, audit, test, or refactor a skill, or when a workflow should be packaged as reusable skill instructions. ---3.1 字段的运行时语义helpers/skills.py 的skill_from_markdown()展示了这些字段如何被消费name技能的规范化标识加载时通过它查找技能description始终可见的精简用途说明参与搜索相关性打分triggers短语匹配的触发器列表用于搜索与相关性召回。解析时兼容trigger_patterns、trigger、activation等别名skills.py此外还支持tags、version、author、license、compatibility、allowed-tools/allowed_tools等可选元数据加载时会一并注入 Agent 上下文skills.py。3.2 命名规则仅使用小写字母、数字和连字符-优先使用动词开头的短名称例如build-skill、review-plugin、host-file-editing。这条规则不只是风格偏好而是运行时校验的硬约束。validate_skill()skills.py强制执行name必填长度 1–64 字符必须匹配^[a-z0-9-]$即只允许小写字母、数字、连字符不能以连字符开头或结尾不能包含连续连字符--description必填且不超过 1024 字符。任何违反规则的前置元数据都会导致该技能在扫描时被跳过。frontmatter 解析失败如 YAML 闭合 fence 缺失同样会导致技能被静默跳过并发出警告对应测试见 tests/test_skills_runtime.py 的test_invalid_skill_frontmatter_reports_yaml_errors与test_invalid_skill_frontmatter_warns_when_skill_is_skipped。四、构建技能的标准工作流WorkflowSKILL.md给出了七步流程识别触发场景找出两到三个真实的、应当触发该技能的用户请求决定归属判断技能应放在核心skills/目录还是放进某个插件的plugins/plugin/skills/目录撰写 frontmatterdescription写入核心触发条件与关键上下文对应当高排名的短用户短语额外添加triggers聚焦正文正文聚焦于流程procedure、契约contracts、失败处理failure handling以及下一步应加载的文件/脚本下沉细节把长篇示例、schema、策略或变体细节移入一层深的references/文件按需添加脚本只为确定性或反复重写的操作添加scripts/并测试代表性脚本验证闭环通过搜索、加载并在一个中位数用户的提示词上实际使用该技能来验证。4.1 触发词如何影响召回从打分源码看triggers的价值为什么第 3 步强调triggers因为 search_skills() 的相关性打分中triggers的权重明显高于description查询词与技能名完全相等10查询词与某个 trigger 完全相等9查询词包含于 trigger 或 trigger 包含于查询词8查询词包含于 name6查询词包含于 description仅4。测试 tests/test_skills_runtime.pytest_browser_skills_rank_for_browser_trigger_phrases验证了这一点browser-automation技能凭借其triggers在 open this URL in my browser and take a screenshot 等查询下稳定排第一。因此触发语言必须放在 frontmatter 中而不是正文里——正文在搜索阶段根本不会被读取。五、放置规则Placement核心目录还是插件作用域插件作用域技能当技能的存在是为了解释某个插件拥有的工具或 UI 界面时应放在插件目录下。例如浏览器工作流属于_browser插件见plugins/_browser/skills/、A0 CLI 宿主机工具属于_a0_connector插件见plugins/_a0_connector/skills/、桌面画布工作流属于_desktop插件核心skills/目录用于不被任何单一插件拥有的 Agent Zero 框架级工作流例如构建技能build-skill、开发核心特性a0-development、管理社区插件a0-manage-plugin、a0-review-plugin等。从源码看get_skill_roots() 会同时扫描skills/、usr/skills/、项目/Agent 作用域以及所有plugins/*/skills/、usr/plugins/*/skills/等根目录因此两种放置方式都会被统一发现对有 Agent 上下文的调用技能按规范化名称去重根目录顺序靠前者优先。管理契约在 skills/AGENTS.md 中亦有声明插件分发的技能归属对应插件目录用户本地技能归属usr/skills/。六、写作纪律Writing Rules触发语言放入 frontmatter不放正文小节description用于紧凑且始终可见的用途说明triggers用于搜索与相关性召回的短语匹配不要在技能文件夹内添加 README、changelog、快速参考或安装指南文件重命名时不要保留兼容性别名直接更新所有对旧名称的引用宁用精炼示例不用长篇散文不要在SKILL.md与 references 中重复同一份指引当多个技能可能同时适用时保持每个技能职责窄化并明确交代交接handoff关系。这些纪律与加载机制相互印证load_skill_for_agent()skills.py会把技能元数据、description、正文及目录文件树一次性拼装进 Agent 上下文同时 skills_tool 的read_file动作会校验file_path必须位于技能目录内部——所以把长材料放进references/并按需读取是控制上下文体积的正确做法。七、验证Validation编辑后的检查清单7.1 自动化测试编辑技能后运行针对性的运行时测试conda run -n a0 pytest tests/test_skills_runtime.py tests/test_tool_action_contracts.py -q其中 tests/test_skills_runtime.py 覆盖了技能加载契约的关键行为frontmatter 解析错误处理、标准字段约束、搜索打分排序、隐藏/激活/停用技能的会话覆盖逻辑、内置插件技能不可删除PermissionError、技能数量上限等test_renamed_skills_use_standard_frontmatter_only甚至直接读取skills/build-skill/SKILL.md等仓库内置技能文件做规范断言。7.2 人工活体验证当技能改变了 Agent 面向用户的工具行为时还需走一遍真实路径1. 用一句简短、普通的提示词提问确认该技能能被发现。 2. 确认 Agent 在适当时机使用 skills_tool 的 search/load。 3. 当工具是技能门控skill-gated时确认 Agent 只在技能加载之后才调用目标工具。skills_tool 的四个动作tools/skills_tool.py——list、search、load、read_file——正是技能发现与加载的入口search走词法打分召回load把完整指令注入上下文read_file按需读取技能目录内的辅助文件。开发者在验证时应重点确认先 search/load、再调工具的顺序不会被跳过。八、额外约束与仓库契约对齐每个技能目录必须包含SKILL.md且 frontmatter 与目录形态的指引必须与技能加载器行为保持同步见 skills/build-skill/AGENTS.md 的 Local Contracts当技能元数据、发现或验证行为变化时应及时更新本技能build-skill 自身的维护契约技能正文不得包含密钥、私有用户数据或环境特定凭据技能引用的仓库路径、命令或插件架构必须与源码和文档保持同步skills/AGENTS.md更改技能加载假设或格式后应运行技能运行时/导入测试并人工通读变更的SKILL.md检查失效的相对引用。九、小结构建一个高质量 Agent Zero 技能本质上是三条线的对齐元数据要精准name/description/triggers 决定被发现与召回、正文要精简只承载流程、契约与失败处理、细节要下沉scripts/references/assets 按需取用。以 build-skill 技能 为范本配合 helpers/skills.py 的解析与打分逻辑、tools/skills_tool.py 的加载入口以及 tests/test_skills_runtime.py 的契约测试你可以在十分钟内产出一个格式正确、可被发现、可被可靠加载的插件技能或框架级技能。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考