一个 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 更像是一个“可以被程序调用的能力模块”而不是一段“给模型读的话”。下面用一张简单的对比表来区分维度AgentSkill核心职责任务理解、规划、决策、调度执行一件具体、可重复的任务是否拥有状态通常有会话状态和上下文设计上尽量无状态输入固定、输出可预期复用粒度偏整体方案难以跨项目直接复用偏能力单元可跨项目、跨 Agent 复用工程资产更像“应用层”更像“工具库”变更影响调整可能影响整个任务链路调整只影响单个能力风险更可控从工程角度讲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 ab # 运行 Agent让它自行决定是否调用 code-review skill response runtime.run(user_request) # 打印输出 print(任务规划:, response.plan) print(调用的 skill:, response.skill_calls) print(最终结果:, response.result)预期的调用链路是:Agent 分析用户请求识别出“评审代码”的意图Agent 选择code-reviewskillskill 按输入定义解析请求内容执行检查逻辑返回结构化结果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 ab, 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, encodingutf-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. 常见问题与排查思路在实践过程中很多团队会遇到相似的问题。下面整理一份常见问题排查表你可以直接按表格里的思路处理。问题现象可能原因排查方式解决方案Agent 完全不调用已注册的 skill触发条件描述不清晰模型无法识别意图查看 Agent 调用日志确认意图识别结果重写 skill 的触发条件和输入定义加入典型请求示例调用了错误的 skillskill 名称或描述之间歧义过大检查相似 skill 的触发条件是否重叠增加区分度或调整优先级配置skill 执行结果不稳定执行步骤描述太模糊模型自由度太高对比多次输出找出变化点把步骤写成确定性的检查流程减少开放式指令生产环境出现未授权操作skill 的权限声明缺失或写得太宽检查 skill 的权限配置和执行日志按最小权限原则收紧权限哪些资源不允许访问必须显式声明skill 升级后行为变化没有版本控制旧逻辑被直接覆盖查看变更记录和版本历史为 skill 建立版本管理升级走灰度发布必要时快速回滚Agent 响应速度明显变慢注册 skill 过多模型决策负担变大统计每次请求的 token 消耗和耗时精简 skill 列表把不常用的 skill 设为 disabled这里特别想提醒一点很多问题表面上是“模型不听话”实际上是因为 skill 的“接口设计”做得不好。输入定义不清、触发条件含糊、输出格式没有约束模型只能靠猜猜错的概率自然很高。把 skill 当成函数来设计而不是当成 prompt 来写很多诡异问题会消失。8. 工程落地最佳实践如果你决定在团队里真正推动 agent skill 的落地下面这些实践建议可以帮你少走弯路。8.1 命名与目录规范skill 的名称建议统一使用小写字母加连字符比如code-review、>