Agent Skills实战：从Prompt到可复用技能包的AI Agent工程化指南

如果你最近在关注 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 在技术版图中的位置，下面用一张表格对比目前主流的几种能力扩展方式：

这个对比可以看得很清楚：传统 Prompt 适合一次性任务，Function Calling 适合单步工具调用，Agent Skills 则适合需要稳定交付高频场景。三者不是互相取代的关系，反而经常叠加使用。成熟的技能包内部通常会调用多个函数，同时包含精心设计的指令片段。

4. 一个标准 Skill 的目录结构与设计规范

既然要工程化，就要有标准。目前业内比较认可的技能包结构，通常包含两类核心元素：知识类文件和执行类脚本。知识类文件描述做什么、怎么做、有什么边界；执行类脚本负责具体的计算、解析、转换等确定性操作。下面是一个典型的目录结构示例：

my-skill/ ├── SKILL.md ├── scripts/ │ ├── analyze.py │ └── report.py └── references/ └── example-output.md

SKILL.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}", "--pretty=format:COMMIT:%h|%an|%s", "--no-merges" ] result = subprocess.run(cmd, capture_output=True, text=True, check=True) 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(description="Analyze recent Git commits") parser.add_argument("--commits", type=int, default=5, help="Number of commits to analyze (default: 5)") args = parser.parse_args() commits = get_commits(args.commits) report = build_report(commits) print(json.dumps(report, indent=2, ensure_ascii=False)) 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. 常见问题与排查思路

技能包开发和实际运行过程中，有几类问题是出现频率最高的。下面用表格整理成一份可以直接对照排查的清单：

这个表格可以作为你日常调试技能包的起点。遇到问题时，优先怀疑 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 框架之间共享技能包的能力会越来越强，现在积累的经验和资产，在标准化落地时会有明显的先发优势。技能包的质量取决于你沉淀的专业深度，也取决于你对模型行为的理解精度。把技能当代码写，把描述当接口设计，这条路值得投入时间。