如果你最近在关注 AI Agent 开发应该会注意到一个现象同一个大模型在 A 手里是“资深程序员”在 B 手里却只会“纸上谈兵”。差距不在模型本身而在你给了 Agent 什么“技能”。这就像给一个人装上了不同的工具箱他解决问题的能力完全不同。最近Google Chrome 团队知名工程师 Addy Osmani 的 agent-skills 项目在开源社区受到不少关注它的核心思路正是把“给 Agent 装技能”这件事从玄学变成工程。这篇文章会一次性讲清楚Agent Skills 到底是什么、和传统 Prompt 工程有什么区别、一个完整的技能包长什么样、如何在项目中自己封装一个可复用的 Agent 技能以及最容易踩的坑在哪里。读完你不仅能用好现成的技能库还能照着标准写出团队自己的技能包。1. Agent Skills 到底解决了什么问题先从一个真实场景说起。假设你要让 AI 助手帮你检查项目里所有 TODO 注释统计每个文件里遗留了多少待办事项并生成一份 Markdown 报告。没有技能包的 Agent 会怎么做它可能会写一段 Python 脚本也可能用 grep 命令还可能要求你手动粘贴文件内容。结果就是每次对话都要重新解释需求模型输出的格式也不稳定今天给你表格明天给你列表后天直接跑偏去分析代码质量了。如果给 Agent 装一个todo-scanner技能情况就完全不同。你只需要说“跑一下 todo-scanner”Agent 就会自动执行技能包里预先写好的指令和脚本用统一的方式扫描、统计、输出报告。这里的关键不是模型变聪明了而是你把“如何完成任务”的专业知识预先沉淀下来了。agent-skills 这类项目解决的核心痛点就是把 AI Agent 从“聊天机器人”变成“能稳定干活的员工”。传统方式下模型每次执行任务都是从零开始推理结果不稳定有了技能库执行路径是预设好的模型只需要按流程调用即可。它解决的是大模型应用中最让人头疼的稳定性和工程化问题。对于正在把 AI 接入团队工作流的开发者来说这是一个绕不开的议题与其每次给模型写临时提示词不如把高频任务固化成标准技能。2. Skills 不等于 Prompt也不等于 Function Calling关于 Agent Skills开发者圈子里有一个普遍误区觉得它不就是把 Prompt 写得更长一点、更结构化一点吗或者说它就是 Function Calling 换了个名字这两种理解都不准确。先看 Prompt。传统 Prompt 是一段自然语言指令模型每次执行都要“阅读理解”一遍不同模型、不同上下文长度下理解结果可能完全不同。Skill 则是高度结构化的工程产物包含指令文件、脚本、配置文件、测试用例它可以像代码库一样管理有版本、有依赖、有可复用性。再看 Function Calling。Function Calling 解决的是“模型如何调用外部工具”的协议问题你定义函数签名模型决定何时调用、传什么参数。但函数本身是原子的一次调用只做一个动作。Skill 解决的是“如何完成一个完整任务”的编排问题它内部可能包含多个步骤、多次工具调用、中间结果处理、异常分支。简单说Function Calling 是技能包里的一个基础零件Skill 是由多个零件组成的完整方案。Agent Skills 的定位更接近“插件”或“子应用”。它不关心模型怎么理解而是给模型一套标准操作流程先读这个配置文件再跑那个脚本然后把结果格式化输出。这种设计让 Agent 的能力边界变得可管理、可测试也让团队里积累的开发经验能够以文件形式传承。3. 从 agent-skills 看 AI Agent 发展的新方向Addy Osmani 是前端与性能优化领域的技术专家长期在 Google Chrome 团队工作。他关注的 agent-skills 方向体现了一个重要趋势AI Agent 的开发正在从“聊胜于无的灵光一现”走向“标准化、可复用、可测试”的工程阶段。2025 年之后关于 Agent 的讨论焦点正在从模型本身的推理能力转向如何构建 Agent 的能力外围。这个转变背后有一个清晰的技术判断大模型的基础能力每年都在进步但模型不会自动知道你的项目规范、你的代码风格、你的业务流程。这些上下文必须通过某种机制注入进去。Skills 就是这种机制之一。它把“业务知识”和“执行能力”打包成一个 Agent 可以直接消费的单元。更值得关注的是头部厂商已经开始推动 Agent Skills 的标准化。OpenAI 等机构先后提出了类似 Agent Skills 的技术规范定义了技能包的目录结构、元数据格式、知识文件与脚本的组织方式。这意味着未来不同的 Agent 框架之间技能包有望互相兼容。一个团队封装的技能可以同时服务于多个 Agent 平台而不是被锁定在某一家厂商的生态里。这正是 agent-skills 方向最有价值的地方它代表的是行业共识的雏形。对于技术决策者来说现在布局 Agent Skills 方向本质上是为团队积累可复用的 AI 工程资产。今天封装好的每一个技能都是明天 AI 应用快速落地的基础设施。3.1 Agent 能力扩展的几种主流方案对比为了帮助理解 Agent Skills 在技术版图中的位置下面用一张表格对比目前主流的几种能力扩展方式对比维度传统 PromptFunction Calling / ToolsAgent Skills本质自然语言指令函数调用接口完整任务解决方案可复用性低每次依赖模型理解中函数可复用但需编排高整体打包复用稳定性不稳定较稳定但只覆盖单步动作高执行路径预设管理方式文本散落代码管理目录化、版本化、可测试跨 Agent 兼容部分兼容依赖各家协议正在走向标准化适合场景简单问答、临时任务模型主动调用工具高频重复的复杂任务这个对比可以看得很清楚传统 Prompt 适合一次性任务Function Calling 适合单步工具调用Agent Skills 则适合需要稳定交付高频场景。三者不是互相取代的关系反而经常叠加使用。成熟的技能包内部通常会调用多个函数同时包含精心设计的指令片段。4. 一个标准 Skill 的目录结构与设计规范既然要工程化就要有标准。目前业内比较认可的技能包结构通常包含两类核心元素知识类文件和执行类脚本。知识类文件描述做什么、怎么做、有什么边界执行类脚本负责具体的计算、解析、转换等确定性操作。下面是一个典型的目录结构示例my-skill/ ├── SKILL.md ├── scripts/ │ ├── analyze.py │ └── report.py └── references/ └── example-output.mdSKILL.md 是整个技能包的入口。Agent 调用技能时先读取这个文件理解任务目标、适用范围、执行步骤。它的设计直接影响技能的成功率。scripts 目录存放可执行脚本用于完成模型不擅长的确定性计算。references 目录则提供参考示例帮助模型理解期望的输出格式和风格。SKILL.md 的内部结构也有成熟的经验可以参考。通常包括技能名称、适用场景、执行步骤、注意事项、输出格式。其中执行步骤是最关键的部分必须写清楚“先做什么、再做什么、遇到什么情况做何处理”。下面是一个技能描述文件的示例结构# Skill: Changelog Analyzer ## Description Analyze the CHANGELOG.md file and summarize all unreleased changes by category. ## When to Use - User asks for a summary of recent changes - User wants to see which files were modified in the unreleased version ## Steps 1. Find the CHANGELOG.md file in the repository root 2. Locate the unreleased section 3. Categorize entries by type: Added, Changed, Deprecated, Removed, Fixed, Security 4. Group by category and output as a Markdown list ## Notes - Only analyze the top-level CHANGELOG.md, do not scan subdirectories - If the unreleased section does not exist, do not guess, report that it is missing这里容易忽略的一个点是“When to Use”字段。很多技能失败不是因为执行步骤写错了而是模型在不需要调用该技能的时候盲目调用或者在应该调用的时候没有识别出来。明确写清技能的触发条件能显著减少误调用。执行步骤也要控制颗粒度太粗模型容易漏步骤太细又过于死板。较好的标准是包含输入、输出、关键判断分支但保留模型灵活处理的中间空间。5. 如何初始化一个技能包环境准备与前置条件动手前先明确环境要求。技能包本质上是一组文件不依赖特定 IDE但建议准备以下环境安装了 Git 的终端环境一个支持 Agent 开发的代码工程目录Python 3.8 以上环境用于运行示例脚本一个支持 Skills 规范的 Agent 框架如 Claude Code、兼容的编程助手等需要说明的是不同框架对技能包的加载方式存在差异版本信息以你实际使用的工具为准。本文示例重点展示通用思路技能包的核心是文件结构和内容组织只要遵循规范迁移到其他框架的成本不会太高。创建技能包的第一步是建立目录和 Git 仓库。这里推荐从一开始就用 Git 管理技能包因为技能包的演化需要版本记录团队成员协作时也方便 review。初始化命令如下mkdir my-skill cd my-skill git init mkdir scripts mkdir references touch SKILL.md git add . git commit -m feat: initialize skill package structure初始化后你就有了一套可以迭代的骨架。接下来最重要的工作是编写 SKILL.md。很多开发者在这里犯的错误是写得过于笼统比如“分析代码质量”这种描述对 Agent 没有任何指导意义。一个有实操性的技能描述应该明确回答三个问题输入是什么、处理逻辑是什么、输出是什么。如果这三个问题的答案都清晰Agent 执行成功率会大幅提升。在写描述的过程中建议同步准备一两个示例放到 references 目录。示例的输出文件是 Agent 的“参照物”它能让模型更准确地理解格式期望比在描述里重复强调格式规范有效得多。后续调试技能时这些示例还能充当测试用例用来验证修改是否破坏已有功能。6. 完整示例从零封装一个代码变更分析技能下面用实战案例完整演示一个技能包的开发过程。我们要封装一个“代码变更分析”技能功能是扫描 Git 仓库最近 N 次提交统计每次提交修改的文件、变更类型和影响范围最后生成结构化的报告。第一步创建技能目录结构mkdir code-change-analyzer cd code-change-analyzer mkdir scripts touch SKILL.md第二步编写 SKILL.md。这里要点是让 Agent 知道什么时候调用、怎么调用脚本、如何解读输出# Skill: Code Change Analyzer ## Description Analyze recent commits in a Git repository to identify which files were changed, what types of changes occurred, and the overall impact scope. ## When to Use - User asks what changed in the last N commits - User wants to review recent modifications before deployment - User wants a quick summary of latest development progress ## Steps 1. Ask the user for the number of commits to analyze, default to 5 if not specified 2. Run python3 scripts/analyze_git.py --commits N 3. Read the output JSON, summarize it into a human-readable report 4. Group changes by directory to show impact scope ## Notes - Only output files that actually exist in the repository - Distinguish between file modifications, new files, and deleted files - Do not include merge commits by default第三步编写核心分析脚本。这个脚本负责确定性最强的部分解析 Git 历史并输出 JSON 结果#!/usr/bin/env python3 # 文件路径code-change-analyzer/scripts/analyze_git.py import argparse import json import subprocess def get_commits(count: int) - list: cmd [ git, log, --name-status, f-{count}, --prettyformat:COMMIT:%h|%an|%s, --no-merges ] result subprocess.run(cmd, capture_outputTrue, textTrue, checkTrue) return parse_git_output(result.stdout) def parse_git_output(output: str) - list: commits [] current None for line in output.splitlines(): if line.startswith(COMMIT:): _, commit_id, author, message line.split(|, 3) current { commit: commit_id, author: author, message: message, changes: [] } commits.append(current) elif line and current is not None: parts line.split(\t) if len(parts) 3: status, old_path, new_path parts current[changes].append({ status: status, old_path: old_path, new_path: new_path }) elif len(parts) 2: status, path parts current[changes].append({ status: status, old_path: path, new_path: path }) return commits def build_report(commits: list) - dict: file_stats {} for commit in commits: for change in commit[changes]: path change[new_path] or change[old_path] if path not in file_stats: file_stats[path] {added: 0, modified: 0, deleted: 0} status change[status] if status A: file_stats[path][added] 1 elif status D: file_stats[path][deleted] 1 else: file_stats[path][modified] 1 return { total_commits: len(commits), total_files_changed: len(file_stats), file_stats: file_stats, commits: commits } def main() - None: parser argparse.ArgumentParser(descriptionAnalyze recent Git commits) parser.add_argument(--commits, typeint, default5, helpNumber of commits to analyze (default: 5)) args parser.parse_args() commits get_commits(args.commits) report build_report(commits) print(json.dumps(report, indent2, ensure_asciiFalse)) if __name__ __main__: main()这个脚本本身不依赖任何第三方库用标准库就能运行降低了使用门槛。它处理的关键逻辑是合并git log --name-status的输出将文件变更状态映射为 added、modified、deleted 三类再按文件路径聚合统计。Agent 拿到这段脚本的输出后不需要自己解析 Git 原始输出直接基于结构化的 JSON 生成自然语言总结即可。第四步运行脚本验证效果。假设当前 Git 仓库最近有 3 次提交执行python3 scripts/analyze_git.py --commits 3预期输出是类似下面的 JSON 结构实际内容取决于仓库历史{ total_commits: 3, total_files_changed: 7, file_stats: { src/main.py: { added: 1, modified: 2, deleted: 0 }, README.md: { modified: 1, added: 0, deleted: 0 } }, commits: [ { commit: a1b2c3, author: zhangsan, message: fix: update main entry, changes: [ { status: M, old_path: src/main.py, new_path: src/main.py } ] } ] }看到 JSON 输出后技能包的核心逻辑已经验证通过。接下来需要将完整的 SKILL.md、脚本和示例提交到 Git 仓库git add . git commit -m feat: complete initial version of code change analyzer skill这一步完成后你的第一个技能包就具备了基本使用条件。把它复制到 Agent 工具支持的 skills 加载目录或者通过工具命令加载就能在对话中直接调用。7. 技能包的运行验证与效果评估技能包装好后不能“感觉能用”就算完成。它本质上是代码资产需要一套客观的验证方式。这里提供一个三级验证思路从简单到复杂逐步深入。第一级是单次功能验证。在干净的仓库上执行一次技能确认输出格式正确、脚本没有报错、Agent 能正确总结数据。这个阶段重点看的是基本功能是否跑通代码有没有明显 bug。第二级是稳定性验证。连续执行 5 到 10 次观察输出是否一致。这里真正要检查的是 Agent 是否正确遵循了 SKILL.md 中的步骤有没有跳过脚本直接猜测结果。稳定性差通常不是脚本的问题而是 SKILL.md 的步骤写得太模糊模型在理解上产生了偏差。第三级是边界场景验证。输入极端情况空仓库、没有最近提交、文件路径包含中文或空格、用户要求分析 100 次提交。这些场景最容易暴露脚本的防御性不足。验证时还需要关注三个指标任务完成率、执行耗时、Token 消耗。任务完成率反映技能包的有效性执行耗时反映步骤编排是否合理Token 消耗则直接关联成本。一个设计良好的技能包应该把确定性的计算交给脚本让模型只做总结和判断从而减少不必要的推理消耗。如果发现模型在某个环节反复“思考”却迟迟不执行脚本说明 SKILL.md 中关于该步骤的描述还不够直接。对于更严谨的团队可以把这些验证场景写成自动化测试纳入 CI 流程。每次修改技能包后自动跑一遍回归确保没有破坏已有功能。技能包的维护和代码维护是同一套方法论引入测试越早后期维护成本越低。8. 常见问题与排查思路技能包开发和实际运行过程中有几类问题是出现频率最高的。下面用表格整理成一份可以直接对照排查的清单问题现象可能原因排查方式解决方案Agent 不调用技能直接凭常识回答When to Use 描述过于狭窄模型未识别触发场景检查 SKILL.md 中触发条件描述补充更多典型场景描述和示例用语技能调用后输出内容与格式要求不符输出格式定义模糊references 示例缺失检查 SKILL.md 的格式规定查看模型实际输出增加标准示例文件到 references 目录脚本报错提示文件找不到技能假设的仓库结构与实际结构不一致查看脚本中硬编码的路径改为参数传入或自动探测仓库根目录脚本执行超时提交数量过大或变更文件过多检查参数设置观察执行时间增加分批处理逻辑限制单次处理数量技能被过度调用干扰正常对话When to Use 边界不清晰回看对话历史中误触发案例收紧触发条件明确“不适用场景”两个技能都匹配度较高发生冲突技能职责重叠检查技能描述的关键词区分度拆分技能或合并为一个更通用的技能这个表格可以作为你日常调试技能包的起点。遇到问题时优先怀疑 SKILL.md 的描述质量其次才怀疑脚本逻辑。从实践经验看大多数技能表现不佳问题都出在“模型不理解何时用、怎么用”上脚本反而很少出问题。另外一个容易被忽略但值得警惕的情况是Agent 在执行技能过程中可能因为环境差异导致命令失败。比如 Windows 系统与 Linux 系统在路径分隔符、编码方式上的差异或者用户没有安装 Python 依赖。技能包设计时要明确标注系统兼容性并在脚本中尽量使用跨平台的实现方式。上面的示例使用纯标准库就是为了尽量减少环境依赖带来的问题。9. 技能封装的最佳实践与工程建议技能包开发有其特殊性它不是普通函数库因为它服务的对象是“会随机理解指令的模型”。这意味着你的描述必须同时兼顾机器可读性和语义清晰度。基于社区实践和项目经验下面几条建议值得在团队内形成规范。第一每条技能只解决一个明确的任务域。一些开发者希望技能包“大而全”把相关功能都塞进去。这样做的问题在于模型判断何时使用技能时会陷入混乱技能的稳定性也会因为步骤过于复杂而下降。一个技能解决一类问题是保持可控性的基本前提。第二脚本承担确定性逻辑模型只做判断和表达。凡是能用几行代码确定完成的事就不要让模型自由发挥。比如解析日志、统计数字、提取字段这些操作模型做起来又慢又容易出错交给脚本才是正确选择。技能包的理想状态是模型读取输入调用脚本得到中间结果最后用自然语言把结果表达给用户。第三SKILL.md 中的步骤要包含异常分支。现实中技能执行不可能永远一帆风顺。文件可能不存在格式可能不符合预期脚本可能返回空结果。这些情况下技能应该告诉模型下一步做什么是报错、重试、还是换一种方案。缺少异常分支的技能很容易在边界场景下陷入死胡同。第四版本管理要细致破坏性变更要同步更新说明。技能包是用 Git 管理的但它的使用者是模型而不是开发者。直接修改 SKILL.md 可能导致正在使用旧版本的 Agent 行为突变。建议在修改技能时先更新示例输出再调整描述最后改动脚本逻辑并按语义化版本打 tag。团队内部可以维护一个技能清单文档记录每个技能包的用途、版本、负责人和最近变更。第五安全边界必须写清楚。技能包可能被 Agent 在任何上下文中触发因此脚本中要有最小权限意识只读取当前仓库的文件不随意执行危险的系统命令不向外部地址发送仓库内容。对于涉及删除、修改、网络请求等敏感操作的技能应在 SKILL.md 中显著标注“需要用户确认后再执行”。这一点在生产环境中尤其重要。第六建立技能包的评审和测试流程。技能包不是写完就完了建议在团队内部走类似代码评审的流程设计评审看技能拆分是否合理代码评审看脚本实现是否有 bug效果评审看真实场景下的任务完成率是否达标。将技能包纳入正式工程体系它才能持续产生价值。10. 总结与后续学习方向Agent Skills 是 AI Agent 工程化进程中一个关键节点。它的核心思想是把人的专业经验固化成模型可以稳定消费的“能力组件”让 Agent 不再依赖每次对话的临时发挥。这篇文章讲清楚了几个关键点Agent Skills 与传统 Prompt 和 Function Calling 的本质区别一个标准技能包的目录结构核心是 SKILL.md、scripts 和 references 的分工协作从零封装一个技能包的完整流程包括初始化、编写描述、开发脚本、运行验证以及技能维护过程中的排查思路和工程规范明确了脚本负责确定性逻辑、模型负责判断表达的边界。如果你准备从零参与这个方向可以按这样的顺序实践先选择一个日常高频、重复性强的开发任务比如代码审查、日志分析、版本发布检查然后照本文的结构封装第一个技能包跑通后在 3 到 5 个真实场景中验证稳定性最后把技能包纳入团队仓库走一套标准的评审和测试流程。过程中要特别关注 SKILL.md 中的触发条件描述它决定了技能什么时候被正确唤起这是最容易出问题也最值得反复打磨的部分。更进一步你可以持续关注 OpenAI、Anthropic 以及各开源社区在 Agent Skills 标准上的演进。未来不同 Agent 框架之间共享技能包的能力会越来越强现在积累的经验和资产在标准化落地时会有明显的先发优势。技能包的质量取决于你沉淀的专业深度也取决于你对模型行为的理解精度。把技能当代码写把描述当接口设计这条路值得投入时间。