最近在帮团队梳理 AI Agent 的工程化落地规范时我发现一个特别普遍的问题很多人不是被模型能力卡住而是被“工程化”卡住。同一个任务在演示环境里跑得很顺一进生产环境就频繁翻车。翻车的原因往往不是 Prompt 写得不好而是缺少一套可以复用、可以测试、可以版本管理、可以团队共享的 Skill 体系。刚好 GitHub 本月热榜上出现了一个非常有代表性的项目由 Google 工程师 Addy Osmani 出品、围绕生产级 agent skill 展开的高热度仓库star 数已经到 7.9 万。这个数字放在整个开源生态里都很夸张也说明 Agent 工程化已经彻底从“概念炒作”进入“生产落地”阶段。这篇文章就顺着这个热点拆开聊一聊重点解决三个问题Skill 和 Agent 到底是什么关系为什么这两个词最近总是被一起讨论一个“生产级”的 Skill 仓库应该长什么样和普通“我写了一个 Prompt”有什么区别怎么从零搭一个能放进团队知识库的 Skill并且保证它能进得了生产环境全文包含完整的目录结构、SKILL.md 示例、Python 解析脚本、pytest 测试和一份高频问题排查清单。新手可以照着理解概念已经在做 Agent 开发的可以把它当成模板改造进团队内部技能包。1. 背景为什么 Addy Osmani 的仓库值得关注1.1 Addy Osmani 是谁Addy Osmani 是 Google Chrome 团队的工程负责人之一也是前端和 Web 性能领域非常资深的开源作者。他的《Learning JavaScript Design Patterns》是很多前端开发者的入门书他在 GitHub 上的多个仓库也长期排在各类技术榜单前列。这里要先解释一个背景Addy Osmani 的公开分享有一个很明显的特征——他很少发纯概念文章而是更喜欢把大型项目里的工程经验抽象成“可以直接抄的实践”。这次关于 agent skill 的项目延续了同样的风格不是告诉你“Agent 很厉害”而是告诉你“生产环境里的 Agent 技能应该怎么设计、怎么写、怎么维护”。所以这个仓库能冲到 7.9 万 star不只是因为作者名气大更关键的是它踩中了当前开发者真实痛点Agent 数量越来越多但每个 Agent 的能力都是“一次性”的换个人、换个项目、换个上下文就失效了。1.2 为什么说这是 Agent 工程化的信号如果你关注过去一年的技术趋势会发现一个明显的转变2024 年大家还在讨论怎么把 Prompt 写长、写复杂希望靠一段“万能提示词”解决所有问题。2025 年开始主流开源社区几乎同步转向了“技能包”思路把能力拆成一个个可独立维护、可测试、可审计的 Skill。GitHub 上的热门仓库、主流 Agent 框架的官方文档、甚至企业内部的 AI 平台建设都在朝着同一个方向走。Addy Osmani 这个项目本质上是把 Google 内部那种“生产级工程素养”带到了 Agent 技能开发里所以它的参考价值并不局限于某一个框架而是一套通用的设计思路。2. 核心概念Skill 与 Agent 到底有什么区别在继续往下看仓库之前先把两个最容易被混淆的概念讲清楚。2.1 什么是 AgentAgent 直译是“智能体”通俗理解就是一个能够自主完成任务的 AI 系统。它和普通“一问一答”的聊天机器人的区别在于三个能力规划能力把一个大目标拆成多个小步骤。工具调用能力可以调用外部 API、命令行、数据库、浏览器等工具。迭代能力执行完一步之后观察结果再决定下一步怎么做。举例来说一个运维 Agent 接到“帮我定位今天凌晨数据库连接数飙升的原因”这个任务后它会先连上监控系统拉数据再查看数据库慢查询日志然后根据结果缩小排查范围最后生成一份报告。这个过程不是一次性 Prompt 能完成的而是 Agent 自主执行的一个多步骤闭环。2.2 什么是 SkillSkill 直译是“技能”在 Agent 工程化语境里它指的是一组结构化的能力包。这个能力包通常包含一份 SKILL.md 说明文件告诉 Agent 这个技能什么时候用、怎么用、有哪些注意事项。可选的脚本或程序用来执行具体的自动化操作。可选的模板、数据文件、参考资料用来统一输出格式或提供领域知识。Skill 解决的核心问题是“知识的固化与复用”。一个经验丰富的 SRE 处理生产事故时脑子里有一套完整流程先看影响面、再拉时间线、然后排查根因、最后写复盘报告。如果每次都要靠 Agent 自己“临场发挥”结果一定不稳定。把这套流程写成 SkillAgent 每次遇到同类任务就会按照同一个高质量标准执行。2.3 Skill 和 Agent 的关系很多人会问有了 Agent为什么还需要 SkillAgent 不是已经能自己做事了吗这里需要区分“能力”和“技能”Agent 是执行主体相当于“人”。Skill 是执行能力包相当于“岗位手册”或“操作 SOP”。一个人很聪明但没有岗位手册他也能干活只是每次干活的方式可能都不一样质量不稳定出了问题也不知道该按什么标准复盘。而有了 SkillAgent 每次都会按照团队沉淀的规范去执行质量可预期、过程可审计、结果可复现。用一个简单的表格对比对比维度AgentSkill本质自主运行的系统可复用能力包是否拥有状态有任务执行过程有状态无本身只是静态资源是否自主决策是需要规划并调用工具否只提供知识和操作流程复用方式一般按场景独立部署多个 Agent 可以共享同一套 Skill维护成本高需要关注运行稳定性相对低重点是内容质量与版本管理典型载体服务、进程、Agent 框架SKILL.md 脚本 模板的目录理论上一个 Agent 可以加载多个 Skill。比如同一个运维 Agent 可以同时加载“事故复盘技能”“容量评估技能”“变更检查技能”不同的任务自动匹配不同的 Skill这样就不需要为每个任务单独构建一个 Agent。2.4 生产级 Skill 和“写个 Prompt”的区别很多初学者会问Skill 不就是把 Prompt 用 Markdown 写出来吗从形式上确实有点像但从工程角度差得很远。一个生产级 Skill 至少要满足五个条件有明确的适用边界描述里写清楚“什么时候用、什么时候绝对不要用”。有可验证的输出模板和脚本保证输出格式稳定可以自动化校验。有测试覆盖脚本逻辑有单元测试说明文件有格式校验。有版本管理技能升级可以回溯出问题可以回滚。有安全边界不随意放行用户输入不做超出最小权限的操作。这才是 Addy Osmani 项目里“生产级”三个字的核心含义。它不是写一个 Markdown 文件而是把 Skill 当作一个正经的软件组件来开发、测试、发布和维护。3. 生产级 Agent Skill 的构成要素理解了概念之后我们来看一个生产级 Skill 仓库在结构和内容上应该包含哪些东西。3.1 目录结构与 SKILL.md 规范目前社区比较通用的 Skill 组织方式是“一个技能一个目录”每个目录下至少包含一个 SKILL.md 文件。目录名就是技能名建议使用小写中划线风格例如incident-review、deploy-check、>skills/ └── incident-review/ ├── SKILL.md ├── templates/ │ └── review_template.md ├── scripts/ │ └── parse_log.py ├── references/ │ └── severity_definition.md └── tests/ └── test_parse_log.pySKILL.md 是核心文件它通常使用带 frontmatter 的 Markdown 格式frontmatter 里写元信息正文里写使用流程。frontmatter 常见的字段包括name技能名称要和目录名保持一致。description技能描述说明该技能在什么场景下使用。这部分会被 Agent 用来做技能匹配所以描述要具体避免空泛。version版本号推荐遵守语义化版本规范。author/maintainers负责人方便后续维护。tags标签用业务域或技术域词汇标注便于检索。3.2 职责边界Skill 只放可复用能力一个常见误区是把 Skill 目录当成“项目代码目录”什么文件都往里放。实际上Skill 应该只包含可复用的能力定义不包含具体的业务数据。举个例子对的把“如何解析 Nginx 错误日志”做成模板和脚本放进 Skill。不对的把某次线上事故的完整日志文件直接塞进 Skill。3.3 版本管理与依赖声明生产级 Skill 一定要有版本概念。Skill 在演进过程中可能会修改输出格式、调整脚本逻辑如果调用方不感知版本变化很容易出现“昨天能跑今天不能跑”的问题。版本管理的做法和普通软件项目类似用 Git 管理 Skill 仓库每次变更走 MR/PR 评审。在 SKILL.md 的 frontmatter 里记录版本号。发布新版本时写 CHANGELOG说明变更内容。如果 Skill 依赖外部 Python 库、Node 包建议在目录内用requirements.txt或package.json声明依赖并在文档中注明最低版本要求。3.4 测试与安全边界Skill 里的脚本属于代码是代码就应该有测试。对于纯函数逻辑比如日志解析、时间格式化、数据脱敏可以用 pytest 或对应语言的测试框架做单元测试。对于 SKILL.md 本身可以写一个简单的格式校验脚本检查 frontmatter 是否完整、字段是否合法。对于涉及命令执行的 Skill要特别注意安全边界不要执行用户原始输入中的命令不要读取权限范围外的文件不要输出敏感数据。4. 实战从零搭建一个生产事故复盘 Skill概念讲再多不如直接动手搭一个。下面我们以“生产事故复盘”这个场景为例完整走一遍从目录创建到测试验证的流程。选择这个场景是因为很多团队在 AI 落地时最先想做的就是“让 Agent 帮忙做 P0 事故复盘”而且它涵盖了模板、脚本、测试三个 Skill 核心要素。4.1 需求分析假设团队每周都会处理不少生产告警其中一部分会升级成 P0/P1 事故。每次事故结束后需要产出复盘报告报告格式要统一根因要基于事实而不是猜测。我们希望这个 Skill 能帮 Agent 完成以下工作读取用户提供的事故描述或日志文件。调用脚本事先解析日志抽取时间线和关键错误事件。按模板生成结构化复盘报告。信息不足时明确标注“待补充”而不是编造根因。4.2 创建项目结构先在本地创建仓库目录mkdir -p company-skills/skills/incident-review/{templates,scripts,tests,references}接着创建 skill 仓库的根 README说明这个仓库的用途和加载方式。然后开始创建核心文件。4.3 编写 SKILL.md文件路径skills/incident-review/SKILL.md--- name: incident-review description: 当需要分析生产环境事故P0/P1并输出结构化复盘报告时使用。适用于日志分析、故障时间线整理、根因梳理和复盘报告生成。 version: 1.0.0 author: platform-team tags: [incident, sre, review, on-call] --- # 生产事故复盘 本 Skill 用于把一次生产事故从“现象描述”整理成结构化复盘报告覆盖时间线、影响面、根因、修复措施、改进项。 ## 使用流程 1. 获取用户提供的事故描述或日志文件路径。 2. 如果提供了日志文件调用 scripts/parse_log.py 解析时间线。 3. 按照 templates/review_template.md 的章节结构输出报告。 4. 如果关键信息缺失必须在对应位置标注“信息不足”并在报告末尾列出需要补充的问题清单。 ## 注意事项 - 只基于事实数据禁止猜测根因。缺少证据时明确说明。 - 涉及用户数据、业务数据时必须先脱敏。 - 事故等级优先级P0 P1 P2。 - 输出语言与用户提问语言保持一致。这里的关键是description字段。它决定了 Agent 在什么情况下会匹配到这个 Skill所以要写清楚应用场景。比如“处理订单超时问题”和“复盘一次线上事故”是两个不同的触发场景描述不清晰会导致 Agent 选错技能。4.4 编写复盘报告模板文件路径skills/incident-review/templates/review_template.md# 事故复盘{{ incident_title }} ## 基本信息 - 事故等级P0 / P1 / P2 - 发生时间 - 恢复时间 - 影响范围 ## 时间线 | 时间 | 事件 | 说明 | | --- | --- | --- | | | | | ## 根因分析 必须基于日志、监控数据、变更记录等事实禁止猜测。 ## 修复措施 - [ ] 立即修复动作 - [ ] 临时方案 - [ ] 长期优化 ## 改进项 - 监控告警 - 变更流程 - 文档与预案 - 待补充问题清单模板的作用是约束输出格式。生产环境中复盘报告往往需要同步给多个团队统一格式能让信息消费效率提高很多。4.5 编写日志解析脚本文件路径skills/incident-review/scripts/parse_log.py#!/usr/bin/env python3 # -*- coding: utf-8 -*- 解析常见格式的日志文件抽取时间线事件。 import argparse import re from pathlib import Path LOG_PATTERN re.compile( r\[(?Ptime\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2})\] r\s(?Plevel\w)\s(?Pmessage.*) ) def parse_timeline(log_path: Path, level: str) - list[dict]: 按级别过滤日志返回事件列表。 events [] with log_path.open(r, encodingutf-8, errorsignore) as f: for line in f: match LOG_PATTERN.search(line) if not match: continue event match.groupdict() if level ALL or event[level] level: events.append(event) return events def main() - None: parser argparse.ArgumentParser(description解析日志并输出事件时间线) parser.add_argument(log, typePath, help日志文件路径) parser.add_argument(--level, defaultERROR, help过滤级别如 ERROR、INFO、WARN) args parser.parse_args() events parse_timeline(args.log, args.level) for ev in events: print(f{ev[time]} | {ev[level]} | {ev[message]}) if __name__ __main__: main()脚本本身很简单核心逻辑是用正则匹配[时间] 级别 消息这种常见日志格式。支持按级别过滤。输出统一格式的时间线方便后续生成报告。在真实项目中日志格式可能更复杂比如有 trace_id、模块名、多行堆栈这时可以按团队实际日志规范扩展正则或者直接接入日志平台 API。这里给出的是最小可运行实现。4.6 编写单元测试文件路径skills/incident-review/tests/test_parse_log.py# -*- coding: utf-8 -*- 日志解析脚本的单元测试。 import sys from pathlib import Path import pytest sys.path.insert(0, str(Path(__file__).parent.parent / scripts)) from parse_log import parse_timeline pytest.fixture def sample_log(tmp_path: Path) - Path: log_file tmp_path / app.log log_file.write_text( [2025-01-06 10:00:01] INFO service started\n [2025-01-06 10:02:30] ERROR connection timeout\n [2025-01-06 10:03:00] INFO retry succeeded\n, encodingutf-8, ) return log_file def test_filter_error(sample_log: Path) - None: events parse_timeline(sample_log, ERROR) assert len(events) 1 assert events[0][level] ERROR assert timeout in events[0][message] def test_filter_all(sample_log: Path) - None: events parse_timeline(sample_log, ALL) assert len(events) 3运行测试cd company-skills/skills/incident-review python -m pytest tests/ -v预期输出是三条用例全部通过。如果脚本后续要支持新的日志格式先在这个测试文件里补用例再改实现可以避免“重构完才发现解析逻辑坏了”的情况。4.7 接入 Agent 并验证Skill 写完之后需要在 Agent 框架里配置技能加载目录。不同框架的配置方式不完全一样但思路是一致的指定技能目录然后让 Agent 在启动时扫描。以通用配置为例# agent 配置示例按你使用的框架调整 agent: name: ops-agent skills_dir: ./skills enabled_skills: - incident-review接入后可以做一个简单验证给 Agent 一个只包含connection timeout错误的小日志文件让它生成一份复盘报告。正常情况下Agent 应该先调用parse_log.py解析日志再按模板输出报告。python scripts/parse_log.py ./sample.log --level ERROR预期输出2025-01-06 10:02:30 | ERROR | connection timeout这一步跑通之后整个 Skill 就从“一堆文件”变成了“Agent 能实际使用的技能”。5. 常见问题与排查思路在开发和使用 agent skill 的过程中有一些问题出现频率非常高这里整理成一张排查表。问题现象常见原因解决思路Agent 不识别新加的 Skillskills_dir 配置错误或 SKILL.md 的 frontmatter 格式有误检查配置路径确认 frontmatter 使用合法 YAML重启 Agent 进程Agent 加载了 Skill 但不按流程执行description 描述太宽泛Agent 对触发场景判断不准确重写 description明确“何时使用、何时不用”用反向描述排除模糊场景脚本在中文路径下报错使用了硬编码路径分隔符或错误编码统一使用 pathlib 处理路径文件读写显式指定编码为 UTF-8多个 Skill 之间出现同名脚本不同技能里的脚本文件名冲突被全局安装覆盖每个脚本使用独立目录调用时使用相对路径或通过入口函数隔离输出报告格式不稳定没有模板约束Agent 自由发挥在 SKILL.md 里强制要求按模板输出并给模板中的必填字段加注释脚本依赖的第三方库没有安装Skill 仓库没有声明依赖在 skill 目录下维护 requirements.txt 或 package.json并在文档中标注安装命令外部输入导致 Prompt 注入用户输入直接拼接到执行指令里对输入做参数化处理不执行用户原始输入中的命令遵循最小权限原则Git 拉取或推送超时本地网络或代理配置异常检查 DNS 与网络连通性合理设置 Git 超时参数联系本地网络管理员处理这里特别强调一下最后一条GitHub 访问问题属于网络环境问题排查时建议先用ping、curl -I这类基础命令确认连通性再检查系统的代理设置。不要使用任何非合规的“加速工具”这类工具容易带来代码安全和账号安全风险尤其不适合出现在企业开发环境里。6. 最佳实践与工程建议6.1 命名与目录规范Skill 目录名使用小写中划线例如redis-failover-check不要使用空格和中文。SKILL.md 的name字段必须和目录名一致否则容易在扫描阶段被忽略。一个目录只放一个技能不要把多个场景塞进同一份 SKILL.md。技能粒度以“能独立描述清楚、能独立测试”为准。6.2 描述字段的写法description是 Agent 选择技能时的核心依据值得花时间打磨。推荐写法是当需要【具体场景】且满足【触发条件】时使用例如【一个典型例子】。 如果只是【不相关的场景】不要使用本技能。这种写法同时给了正向触发条件和反向排除条件能明显提高技能匹配准确率。6.3 安全边界生产级 Skill 必须考虑安全尤其是涉及命令执行或数据读取的脚本不要信任用户输入的文件路径尽量限制在指定工作目录内。不要直接把外部输入拼接到 shell 命令中优先使用 Python 的subprocess.run并以列表形式传参避免 shell 注入。涉及敏感数据时在脚本内做脱敏处理保证输出到报告中的内容不包含密钥、Token、手机号等。遵循最小权限原则Skill 能读日志就不要给写权限能查只读接口就不要给管理权限。6.4 测试与 CISkill 里的脚本逻辑建议纳入 CI。在 GitHub Actions 或自建 CI 中可以加一个简单的任务name: skill-test on: push: paths: - skills/** pull_request: jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.11 - run: pip install pytest - run: find skills -name requirements.txt -exec pip install -r {} \; - run: python -m pytest skills --maxfail1这样每次有同学修改 Skill 里的脚本CI 都会自动跑一遍测试避免把坏的脚本合入主干。6.5 版本管理与发布使用 Git 管理 Skill 仓库变更走评审流程。每次变更升版本号并在 CHANGELOG 里记录。大版本升级比如输出格式变化要提前通知使用方给出迁移说明。在企业内部使用时建议区分“沙箱环境”和“生产环境”两个技能仓库先在沙箱验证再通过发布流程同步到生产。6.6 知识库建设Skill 本质上是一种“可执行的团队知识”。它的沉淀方式比普通文档更利于复用文档只是给人看的Skill 可以同时给人看、给 Agent 用。团队建设 Agent 技能库时建议每次复盘完事故顺手把这次用到的经验固化成 Skill 或 Skill 内的 references 文件。把重复出现的问题场景排优先级优先写“高频、低容错”的技能。指定明确的维护 owner避免技能库变成无人维护的垃圾仓库。7. 结尾从热门仓库到你的生产环境Addy Osmani 这个项目能拿到 7.9 万 star本质上不是因为作者写了多惊艳的代码而是它把 Agent 技能开发从“玄学”变成了一套工程规范。Skill 与 Agent 的边界、SKILL.md 的写法、技能目录的组织方式、测试和安全要求这些才是真正能长期复用的资产。如果你所在的团队正在做 Agent 落地我建议不要急着追下一个热门框架而是先花两周时间做一件事把手头一个高频场景写成 Skill配上模板、脚本和测试放进 Git 仓库并在团队里跑一轮真实任务。运行一个月后再回头看你会发现 Agent 项目的稳定性提升往往不是模型变强带来的而是这些看起来不起眼的工程细节堆出来的。本篇文章的完整示例可以直接改造成团队内部技能包。如果觉得对你有帮助可以收藏备用后续遇到 Skill 开发相关的问题也能随时回来翻一翻。