生产级Agent Skill：从Prompt到可复用工程资产的关键跨越

一个 7.9 万星的 GitHub 项目，如果放到两年前，大概率是一个前端框架、一个后端工具库，或者一个“程序员人手一个”的开发效率神器。但这次不一样:这个项目由 Google 工程师 Addy Osmani 出品，标题里的关键词不是“framework”，也不是“library”，而是agent skill。

很多人第一眼看到“agent skill”会默认理解成“Agent 的一个技能”，就像给 ChatGPT 加一个插件一样，觉得不过尔尔。但真正把它放在工程语境里拆开看，会发现这件事比想象中更接近 Agent 应用落地的一个分水岭：当 AI 能力开始变成可以被版本管理、被复用、被安全审计的技能包，Agent 才真正从“聊天机器人”走向“生产工具”。

这篇文章不打算只停留在“这个项目很火”的层面。我会先从 Addy Osmani 这个人和 7.9 万星背后的信号讲起，再展开 skill 与 agent 的核心区别、生产级 skill 的关键特征、具体怎么封装一个 skill、怎么接入、怎么验证、怎么排查问题。如果你正在做 AI 应用、Agent 平台或者内部工具链，这篇文章应该能帮你建立一套“如何把 AI 能力工程化”的清晰框架。

1. 一个 7.9 万星项目，说明 Agent 工程化到了转折点

先看一个事实:在 GitHub 上，一个项目能拿到 7.9 万星，已经不是“小圈子自嗨”的量级。就算作者是 Addy Osmani，这个传播量也说明项目切中了某种真实需求。

Addy Osmani 是谁?他是 Google 的工程师，长期在 Chrome 团队做 Web 性能和前端工具链方向的工作，写过《Learning JavaScript Design Patterns》《Image Performance》这些被大量开发者阅读的书，也参与过 Lighthouse、Workbox 等知名开源项目。在 GitHub 上，他的账号本身就是一块金字招牌，但他并不是一个喜欢“做营销项目”的人。他出的东西，通常有一个共性:解决真实工程问题，而不是造概念。

这个 agent skill 项目能爆发，本质上是因为它给出的答案正好卡在了当前 AI Agent 发展最痛的那个位置。

过去一年，做大模型应用的团队普遍会遇到一种情况：用大模型做一个 Demo 很容易，写几个 prompt、接一个 API、聊几句就出效果。但一旦要把能力放进生产环境，问题立刻变成：

• prompt 散落在代码里，改一个词都要重新发版；
• Agent 的能力边界模糊，不该执行的动作它可能执行；
• 没有评测标准，每次模型升级都不知道会不会“变傻”；
• 团队里沉淀的“最佳实践”无法复用，换个人、换个项目又要重来。

传统的软件工程解决这些问题靠的是模块化、版本控制、测试、权限管理。而 Agent 时代，这些能力需要落到一个新的载体上，这个载体就是skill。

所以 7.9 万星并不是一个偶然的数字。它说明大量开发者正在寻找一种“把 AI 能力从 prompt 升级为工程资产”的方法论，而生产级 agent skill 恰好提供了这个方向。

2. Skill 到底是什么：和 Agent 的区别与关系

关于 skill 和 agent，我看到很多人的理解是模糊的。有人把 skill 当成 agent 的“子功能”，有人觉得 skill 就是 prompt 模板的换皮，还有人干脆认为 agent 和 skill 是同一个东西。这些理解都不够准确，在实际做工程时会吃亏。

先用一句话给出核心判断：

Agent 是决策调度者，Skill 是可复用的执行单元。

Agent 负责理解任务、拆解步骤、决定“接下来调用哪个 skill”；Skill 负责真正完成一件具体的事，比如“评审代码”“查询数据库”“生成测试用例”。

这两个概念的关系，类似人与工具的关系。Agent 是那个“人”，skill 是“工具箱里的工具”。人负责判断当前场景该用扳手还是螺丝刀，工具负责把螺丝拧紧。工具本身不关心整体工程怎么推进，但它必须能被快速调用、替换、升级。

如果只看表面，很容易误以为“skill 就是给 agent 写一段 prompt”。实际上，生产级 skill 包含的内容远不止 prompt，它会涉及输入输出定义、执行权限、错误处理、评测标准、版本信息等等。一个完整的 skill 更像是一个“可以被程序调用的能力模块”，而不是一段“给模型读的话”。

下面用一张简单的对比表来区分：

从工程角度讲，skill 的价值在于“最小可复用单元”。你可以给同一个 Agent 配十种 skill，也可以在多个 Agent 之间共享同一种 skill。这种设计让 AI 能力的沉淀方式越来越像传统软件里的“库”和“包”，而不是散落在对话里的“灵光一现”。

3. 生产级 Skill 和玩具级 Skill 的本质区别

很多人写过一个 skill 之后，会觉得“这也不过如此”。这很正常，因为写一个能跑的 skill 门槛确实不高，但要达到“生产级”，还差着几个关键维度。

3.1 可复用性

玩具级 skill 通常和具体场景绑死。比如在某个项目里写一段“帮我总结这段日志”的 prompt，换个日志格式、换个输出目标，它就失效了。生产级 skill 必须显式定义输入、输出和触发条件，让不同项目、不同 agent 可以把它当作稳定的能力来使用。

3.2 可测试性

这一点是生产级和玩具级最重要的分水岭。写一个 prompt 很难测试，你只能依赖主观感觉“看起来还行”。但一个生产级 skill 应该有一组测试用例，输入什么、期望输出什么、边界情况是什么，都可以自动化验证。

3.3 可观测性

生产环境里，AI 调用一定会失败，一定会出现不符合预期的情况。skill 如果是一个黑盒，出了问题你根本不知道是 prompt 写得不对、模型理解偏了、还是权限配置错了。生产级 skill 需要暴露足够的执行信息和日志链路，让开发者能定位问题。

3.4 可控性

这里包括权限控制和执行边界。一个生产级 skill 在被 Agent 调用时，应该遵循最小权限原则：能读就不要写，能写当前目录就不要写整个磁盘。skill 本身要明确自己能访问什么资源、不能访问什么资源，避免 Agent 在意图理解出错时执行危险操作。

3.5 版本管理

模型会升级，prompt 会调整，业务需求会变化。生产级 skill 应该像代码一样有版本、有变更记录、可以回滚。如果 skill 只是随手改一改，没有版本概念，那线上环境就可能因为一次“小调整”出现无法解释的行为变化。

总结一下：玩具级 skill 是给模型看的“说明书”，生产级 skill 是给系统用的“可执行资产”。前者依赖模型“读懂”，后者靠工程手段保证“可控、可测、可复用”。

4. 生产级 Skill 的典型结构与设计

现在来看一个生产级 skill 通常应该包含哪些内容。这里不绑定任何特定平台，而是讲通用设计。各个 Agent 框架的 skill 格式会有差异，但核心要素是相似的。

一个生产级 skill 通常会包含：

• 元信息：名称、版本、作者、描述、变更记录；
• 触发条件：什么情况下 Agent 应该调用这个 skill；
• 输入定义：需要哪些参数、参数类型和约束；
• 执行步骤：能力的具体行为逻辑，可能是自然语言指令，也可能是代码；
• 输出定义：返回什么结构、什么格式；
• 权限声明：执行时允许访问的资源范围；
• 错误处理：执行失败怎么办，如何向 Agent 返回可理解的错误信息；
• 测试用例：用于验证 skill 行为是否符合预期。

下面是一个简化的 skill 描述示例，用来直观感受“说明书”和“工程资产”的差别。文件路径可以类似skills/code-review/skill.md。

# 技能名称：代码评审助手 ## 元信息 - 名称: code-review - 版本: 1.2.0 - 作者: platform-team ## 触发条件 当用户提交一份代码片段或 PR 描述，并要求进行代码评审时触发。 ## 输入定义 - code: 需要评审的代码片段（必填，字符串） - focus: 评审关注点（可选，枚举：correctness/security/performance/style） - language: 代码语言（可选，字符串） ## 执行步骤 1. 根据 language 判断语法上下文； 2. 按 focus 指定的关注点逐项检查； 3. 对每个发现的问题，标记严重级别（critical/warning/suggestion）； 4. 输出结构化评审结果。 ## 输出定义 返回 JSON 结构： { "summary": "总体评价", "issues": [ { "severity": "critical|warning|suggestion", "location": "代码位置或片段", "message": "问题说明", "suggestion": "修改建议" } ] } ## 权限声明 - 只读权限：无 - 写权限：无 - 网络访问：禁止 ## 错误处理 - 输入为空：返回错误码 INVALID_INPUT； - 语言不支持：返回错误码 UNSUPPORTED_LANGUAGE，并提示支持的语言列表。

这个描述文件的意义在于，它把 skill 的输入、执行、输出、权限全部显式化了。Agent 看到这个文件就能判断“什么时候该调用我、我有什么能力、我有什么边界”。人看到这个文件也能理解这个 skill 是做什么的，能不能被自己的项目复用。

5. 如何把一个 Skill 接入你的 Agent

接入 skill 的方式取决于你用的是哪种 Agent 框架。有的框架支持在配置里声明 skill，有的框架需要把 skill 文件放进指定目录。不管哪种方式，通用的接入步骤是相似的。

5.1 环境准备

在生产环境中接入 agent skill，建议准备以下条件：

• 一个支持 skill 机制的 Agent 框架或平台；
• 可用的模型推理环境，比如 API 网关或本地推理服务；
• 代码管理仓库，用于保存 skill 文件和版本历史；
• 一个独立的测试环境，用于验证 skill 行为，不要直接在线上环境改配置。

如果条件有限，先用一个最小 Demo 项目跑通流程，再加到真实业务里。

5.2 注册 Skill

大多数平台会把 skill 放在一个约定目录里，例如：

my-agent-project/ ├── agent.yaml └── skills/ ├── code-review/ │ ├── skill.md │ └── test_cases.json └──># agent.yaml name: dev-assistant description: 开发助手 Agent，提供代码评审、数据查询、测试生成能力 model: provider: your-model-provider name: your-model-name skills: - name: code-review version: 1.2.0 enabled: true - name:># 文件路径：examples/run_skill_demo.py from agent_runtime import AgentRuntime # 初始化运行时，传入 agent 配置 runtime = AgentRuntime(config_path="./my-agent-project/agent.yaml") # 用户请求 user_request = "帮我评审这段 Python 代码：\ndef add(a, b):\n return a+b" # 运行 Agent，让它自行决定是否调用 code-review skill response = runtime.run(user_request) # 打印输出 print("任务规划:", response.plan) print("调用的 skill:", response.skill_calls) print("最终结果:", response.result)

预期的调用链路是:

• Agent 分析用户请求，识别出“评审代码”的意图；
• Agent 选择code-reviewskill；
• skill 按输入定义解析请求内容，执行检查逻辑；
• 返回结构化结果；
• Agent 把结果整理成用户可读的回答。

如果你看到的日志里，Agent 没有调用任何 skill，而只是直接基于 prompt 回答，那就要检查 skill 的触发条件和输入定义是否写清楚了。

6. 如何验证 Skill 是否达到生产标准

Skill 接入之后，不能只看“那次调用成功了”，要有系统性的验证机制。

6.1 准备测试用例集

每个 skill 都应该有一组测试用例，覆盖正常输入、边界输入、非法输入和错误场景。一个简单的测试用例文件可以是 JSON 格式：

{ "skill": "code-review", "test_cases": [ { "id": "case_001", "input": { "code": "def add(a, b):\n return a+b", "focus": "correctness", "language": "python" }, "expected": { "has_critical_issue": false } }, { "id": "case_002", "input": { "code": "", "focus": "security", "language": "python" }, "expected": { "error_code": "INVALID_INPUT" } } ] }

6.2 自动化评估脚本

针对上面的测试用例，可以写一个简单的评估脚本，把 skill 的输出和期望结果做比对：

# 文件路径：tests/evaluate_skill.py import json from agent_runtime import run_skill def evaluate(skill_name, test_file): with open(test_file, "r", encoding="utf-8") as f: suite = json.load(f) results = [] for case in suite["test_cases"]: try: output = run_skill(skill_name, case["input"]) passed = compare(output, case["expected"]) except Exception as exc: passed = False output = {"error": str(exc)} results.append({ "id": case["id"], "passed": passed, "output": output }) passed_count = sum(1 for r in results if r["passed"]) print(f"通过率: {passed_count}/{len(results)}") return results def compare(output, expected): # 简化版对比，真实场景需要根据字段逐项匹配 if "error_code" in expected: return output.get("error_code") == expected["error_code"] return output.get("has_critical_issue") == expected.get("has_critical_issue") if __name__ == "__main__": evaluate("code-review", "./test_cases.json")

评估脚本的关键作用，是让 skill 的“好”和“不好”变成可量化的数据。比如通过率 80% 和 95%，就对应着能不能上生产环境的判断依据。

6.3 判断成功的标准

一次完整的验证，应该覆盖以下几点：

• 正常场景的输出是否符合预期格式；
• 边界输入是否报合理错误，而不是模型自由发挥；
• 权限声明是否生效，非法操作是否被拦截；
• 多个 skill 之间是否存在命名冲突或调用冲突；
• 在测试环境下连续运行多次，观察有没有随机失败。

如果 skill 在测试集上通过率稳定达到团队设定的阈值，并且边界情况处理正确，才可以考虑发布到生产环境。不要在一次演示成功之后就直接上线。

7. 常见问题与排查思路

在实践过程中，很多团队会遇到相似的问题。下面整理一份常见问题排查表，你可以直接按表格里的思路处理。

这里特别想提醒一点：很多问题表面上是“模型不听话”，实际上是因为 skill 的“接口设计”做得不好。输入定义不清、触发条件含糊、输出格式没有约束，模型只能靠猜，猜错的概率自然很高。把 skill 当成函数来设计，而不是当成 prompt 来写，很多诡异问题会消失。

8. 工程落地最佳实践

如果你决定在团队里真正推动 agent skill 的落地，下面这些实践建议可以帮你少走弯路。

8.1 命名与目录规范

skill 的名称建议统一使用小写字母加连字符，比如code-review、>