能把“会聊天”的大模型变成“会干活”的队友靠的就是一套成体系的技能库。你手里那个标题agent-skills往小了说是给 AI 助手塞几个脚本模板往大了说是决定智能体在生产环境里到底能扛多少事的关键设计。我最近几周把手上几个项目全部迁移到了基于技能库的架构上最大的感受是以前调 prompt 是求模型发挥现在写技能是规定流程这俩完全是两种干活方式。如果你正在做 AI 应用或者想把大模型集成到团队工作流里尤其被“模型什么都会一点但真到关键步骤总差一口气”折磨过那这篇东西应该能帮你省掉几个月的试错。我会从技能库的核心设计、目录结构、实操步骤、工具链落地到踩坑排查完整拆一遍agent-skills这套玩法。1. agent-skills 到底是什么从“会聊天”到“会干活”1.1 为什么突然大家都在谈技能库先理清一个背景。过去我们调大模型习惯把所有指令塞进一段 System Prompt告诉它“你是某某专家请按照以下规则工作”。这种方式在小任务里够用但一旦场景复杂Prompt 会迅速膨胀到几千字里面既有角色设定、又有业务规则、还有输出格式要求。模型处理这么多混合信息很容易顾此失彼今天记得遵守格式明天就把规则丢了。agent-skills解决的就是这个问题。它的思路很朴素把完成某类任务所需的流程、规则、代码片段、参考示例、输出模板打包成一个独立的“技能”模块Agent 接到任务时按需加载对应的技能包而不是把所有知识都背在身上。这相当于把大模型从一个“全科医生”变成“带工具箱的分诊医生”——遇到什么病症打开对应的工具箱按标准流程处理。我打了个比方这就好比新人入职。你给他一本一千页的《公司制度全编》他大概率记不住。但你给他十个标准作业流程手册每个手册负责一个具体场景报销怎么走、代码怎么提交、客服工单怎么分级他上手就会快得多。技能库就是那些标准作业流程手册。1.2 技能和普通 Prompt、工具的边界在哪很多人会把技能和 Prompt 工程、Function Calling 混在一起实际上三者是不同层面的东西。普通 Prompt 是“一次性指令”它只对当前这次对话生效。你让它今天按某种格式输出明天换个需求又得重新写。技能是“可复用资产”它把指令、流程、示例、校验规则固化成一个文件包在任何对话里都能加载还能跨项目共享。工具Function/Tool是“原子操作”比如查天气、发邮件、执行一段 SQL它负责一个单一动作没有流程概念。技能是“组合动作”它内部可以串联多个工具调用还能根据中间结果做分支判断。举个例子“生成 API 文档”这个技能内部会调用代码解析工具、模板渲染工具、甚至是自动发 PR 的接口这一串动作被编排成固定流程才叫技能。再说得直白一点工具是零件技能是装配工艺Prompt 是口头吩咐技能是书面标准书。我在实际项目里的分工是能写成工具的逻辑尽量写成工具工具解决“能不能做”高层面的业务路径和决策规则交给技能技能解决“怎么做才对”。1.3 一个技能的最小组成单元一个合格的技能至少应该包含三样东西声明文件、操作流程、参考资料。我这里不推荐把逻辑全部塞进一个大文件拆分清楚后续才维护得动。声明文件通常叫SKILL.md负责告诉 Agent“这个技能是干什么的、什么时候该用、需要什么输入、会产出什么”。操作流程定义具体执行步骤可以是文字步骤也可以是伪代码可以引用脚本。参考资料则包括检查清单、规范文档、代码示例、历史案例这些是模型在推理时的依据。三者的关系就像菜谱菜品说明声明、烹饪步骤流程、食材图鉴和摆盘参考资料。只有步骤没有资料的技能模型执行起来容易跑偏只有资料没有步骤的技能模型不知道从哪一步开始。这个结构我踩过不少坑才固定下来后面会展开讲每一部分怎么写。2. 技能库的整体设计目录结构、命名与注册机制2.1 目录结构怎么搭才不失控技能多了以后最怕的就是找不着、调不动、改不动。我建议从一开始就按“领域 / 场景”来组织目录而不是按“技能类型”组织。下面这个结构是我目前在用的模板。skills/ ├── registry.json ├── code-review/ │ ├── SKILL.md │ ├── references/ │ │ ├── checklist.md │ │ └── rule_examples.md │ └── templates/ │ └── review_report.md ├── api-doc-generator/ │ ├── SKILL.md │ ├── scripts/ │ │ └── openapi_to_markdown.py │ └── references/ │ └── style_guide.md └── oncall-troubleshooting/ ├── SKILL.md ├── runbooks/ │ └── database-cpu-saturation.md └── scripts/ └── collect_metrics.sh目录按“技能名”平铺每个技能文件夹内部再按“声明 / 脚本 / 参考 / 模板”分子目录。好处是职责清晰scripts放可执行代码references放模型推理时需要的参考文档templates放输出模板避免把所有文件堆在一个目录里。层级不要挖太深我见过有人把技能目录套了四层最后 Agent 找文件找半天甚至路径超长报错。一级目录就是技能名二级目录就是那几个固定分类保持扁平化检索和维护都轻松得多。2.2 registry.json 注册表的作用有了目录还不够你还需要一个注册表告诉 Agent 有哪些技能可用、每个技能的用途是什么、触发条件是什么。registry.json就是这个注册表。我见过不少团队跳过注册表直接把技能文件夹丢给 Agent结果 Agent 根本不知道有这些技能或者把所有技能都当成背景知识读一遍上下文爆炸。注册表的作用是让 Agent 先“看菜单”再“点菜”而不是把整个厨房搬到面前。{ version: 1.0, skills: [ { name: code-review, description: 对 Python/Go 代码变更进行系统性审查输出风险分级报告, path: ./skills/code-review, triggers: [pr_created, review_requested], inputs: [diff, repo_language], outputs: [review_report] }, { name: api-doc-generator, description: 从 OpenAPI 描述自动生成结构化的 API 文档, path: ./skills/api-doc-generator, triggers: [api_changed, doc_requested], inputs: [openapi_file], outputs: [markdown_doc] } ] }注意description字段这直接影响 Agent 能不能正确选到技能。不要写“用于代码审查”这种泛泛而谈的描述要写清楚“什么场景下、输入什么、产出什么”。我在项目里见过 Agent 因为描述含糊把代码审查技能拿去做了代码生成结果自然是一团糟。2.3 命名规范与版本管理技能命名是另一个容易被忽视的设计点。我的规则是用小写字母加中划线一眼能看出技能用途比如code-review、api-doc-generator、db-migration-check。避免用抽象词比如helper、utils、common这种名字完全没有信息量Agent 根本不知道怎么选。版本管理我直接用 Git 标签 注册表里的 version 字段配合。每个技能的迭代都走 Git 提交记录发版时打 tag。调用方可以锁定技能版本避免“昨天还好好的今天升级完就炸了”的情况。团队协作时技能库作为一个独立仓库维护用 Pull Request 流程审核技能变更谁改了技能、为什么改都有记录。这个习惯一开始可能觉得麻烦但技能数量超过 20 个之后没有版本管理就是灾难。我曾经有一次更新了一个公共技能没打版本号结果三个项目同时遭殃排查了一整天才定位到是技能行为变化导致的。3. 实操从零构建一个可用的技能3.1 用 SKILL.md 定义触发条件和执行流程纸上谈兵没什么意思我直接拿“代码审查”这个技能举例带你走一遍完整流程。在这个案例里假设团队用 GitPR 是你唯一的代码合并方式希望 Agent 能在 PR 提交后自动给出审查意见。先写SKILL.md的声明部分--- name: code-review description: 对代码变更进行系统性审查输出风险分级报告适用于 PR 评审场景。 version: 1.2.0 triggers: - PR 创建或更新 - 用户显式要求审查代码 inputs: diff: git diff 内容 repo_info: 仓库路径、主要语言、测试框架 outputs: review_report: 分级风险列表与修改建议 --- # 技能执行流程 1. 读取 git diff识别变更文件类型源码/测试/配置/文档。 2. 按语言匹配审查规则见 references/checklist.md。 3. 对每一处变更执行以下检查 - 是否存在语法错误或明显的逻辑漏洞。 - 是否遵循仓库已有的代码风格。 - 是否有遗漏的边界条件处理。 - 是否有安全风险如注入、敏感信息硬编码。 4. 生成分级报告P0必须修复、P1建议修改、P2可选优化。 5. 输出报告到 templates/review_report.md 定义的格式。triggers告诉 Agent 什么时候该启用这个技能inputs和outputs定义了技能的接口契约。执行流程尽量用“动词 检查点”的方式描述让模型有明确的步骤感。不要写“全面分析代码质量”这种大而空的话要拆成可执行的小检查项。3.2 参考资料怎么组织才不会被模型忽略参考资料是技能库最容易注水的地方很多人放了一大堆规范文档结果模型根本读不完或者读了也不按规范执行。我的经验是参考资料要精炼、要经过结构化整理不要直接把官方文档原文往里塞。references/checklist.md我一般写成下面这种检查清单尽量用“是/否”或简短回答就能完成的形式# 代码审查检查清单 ## 通用检查 - [ ] 是否存在硬编码的密钥、Token、IP 地址 - [ ] 是否有 Debug 输出遗留 - [ ] 异常路径是否有关键日志 ## Python - [ ] 是否处理了可能抛出的异常 - [ ] 是否避免了可变默认参数 - [ ] 数据库连接是否显式关闭 ## Go - [ ] error 是否被显式处理 - [ ] goroutine 是否有退出机制 - [ ] 是否存在可复现的并发竞争风险检查清单的好处是模型可以像做任务表一样逐项勾选而不是在长篇大论里找重点。我测试过把规范从 5 页缩短成 30 行检查清单之后技能输出的一致性好了一倍不止。模型是概率推理机器你给它的信息越结构化它的推理就越稳定。另外我建议把“正面示例 / 反面示例”放在参考资料里。比如规则“避免可变默认参数”配一个错误写法和正确写法的对比。模型学示例的速度比学规则快得多这个特性在技能设计中要充分利用。3.3 工作流接口输入参数、校验规则与输出格式技能如果只是“给一段文本让模型自由发挥”那和普通 Prompt 没有本质区别。一个真正可用的技能要有明确的接口契约输入要校验输出要有格式约束。在我的实践里输入侧至少要做三层校验一是是否缺少必填参数二是参数类型是否匹配三是参数范围是否合理。比如code-review技能的diff参数如果为空直接终止技能并提示“无可审查内容”而不是让模型硬编一段空话。这可能听起来很基础但很多 Agent 应用翻车就是翻在这些基础校验上。输出侧我用模板来约束格式。templates/review_report.md长这样# 代码审查报告 - 审查时间: {timestamp} - 变更文件数: {file_count} - 总体结论: {conclusion} ## P0 必须修复 {list_p0} ## P1 建议修改 {list_p1} ## P2 可选优化 {list_p2} ## 审查人备注 {agent_note}固定输出模板有两个作用一是让下游处理比如自动在 PR 上评论变得简单可靠不用每回都解析自由文本二是反向约束模型让它知道这个任务最终要产出什么避免发散。我在实践里发现输出格式一旦稳定整个技能的质量都会跟着稳定。3.4 让 Agent 能自我评估与错误修正这是agent-skills设计里含金量最高的部分也是我踩坑最多的地方。模型一次性输出的结果很少是完美的尤其遇到复杂任务。与其期望它一步到位不如在技能内部设计一个“自我检查—修正—再输出”的循环。我在技能流程里加了一步显式的self_check6. 自我检查 - 报告是否覆盖了所有 P0/P1/P2 项 - 每条意见是否都对应了具体的代码位置 - 是否存在凭空捏造的“问题” - 修改建议是否具备可操作性 7. 若自我检查不通过回顾 diff 与检查清单修正报告后重新输出。这一步听起来简单实际效果非常明显。加了自我检查环节之后我的技能输出里“幻觉类错误”——比如指出一个代码中根本不存在的 bug——显著降低了。原理是让模型在最终输出前多一步推理链的验证相当于给它一个“检查作业”的机会。模型在生成时允许自己犯错但在验证时会调取更多上下文来纠错这个机制比单纯在 Prompt 里写“请准确”有用得多。不过也要给自我检查设置上限。我规定最多迭代三次超过三次就带着当前结果上报避免模型在内部循环里空转耗时间又耗 token。实操中你可以在技能里加一个max_retries: 3字段并且每次修正后要求模型简要说明“改了什么、为什么改”方便追溯。4. 常见工具链里怎么落地 agent-skills4.1 IDE 场景从 Cursor 到 Claude Code如果你用的是 Cursor 或者 Claude Code 这类 AI 编程工具它们对技能机制的支持已经相当成熟了。通常做法是在项目根目录建一个.cursor/skills/或类似目录把技能文件夹放进去工具的 Agent 会自动感知技能的存在并在任务匹配时主动加载。我个人的习惯是把“团队级公共技能”放在独立技能仓库里用脚本按需同步到项目目录。这样既能集中管理又不妨碍项目内使用。有人直接把整个技能库塞进每个项目短期内没什么时间长了项目仓库会非常臃肿而且技能更新跟不上。在 IDE 场景里技能最实用的几个用途包括自动生成符合项目风格的代码、执行多文件重构前的检查、生成变更说明和提交信息、按仓库既有规范写单元测试。这些任务都有很强的场景属性和固定套路非常适合固化成技能。这里有个提示IDE 工具的技能机制可能各自不同有的识别SKILL.md约定有的靠特定配置文件。建议你对照自己使用的工具文档确认技能目录的规则。基本原理都是相通的换工具不至于推倒重来改改路径就能适配。4.2 开源 Agent 框架里的技能注册机制除了 IDE更常见的落地场景是在自己的 Agent 应用里集成技能机制。LangChain、CrewAI、OpenAI Agents SDK 这些主流框架都支持自定义工具和流程编排完全可以在此基础上构造成体系的技能库。我在项目里一般这样做用框架原生的 Tool 封装技能内部的可执行动作比如“读取 diff”“执行静态检查脚本”“生成模板”然后写一个顶层的技能调度模块。调度模块读取registry.json根据用户请求匹配合适的技能把技能涉及的 Tool、Prompt、参考资料组合起来形成一个完整的执行单元。这样做的好处是框架本身的 Agent 循环、多智能体协作、模型切换能力都不受影响技能层只是加了一层业务编排的“皮”。而且这层“皮”是可插拔的——今天用 LangChain明天想换别的框架技能资产本身不需要大改只需改调度层的适配代码。4.3 注意区分技能与 MCP 这类协议现在很多团队也在用 MCP 来做模型与外部系统的连接有人会问有了 MCP还需要技能库吗我的答案是两者解决的不是同一个问题。MCP 解决的是“模型如何调用外部工具”的通信协议问题它让模型可以访问数据库、文件系统、第三方 API技能解决的是“如何把一堆动作编排成符合业务标准的工作流”的问题。你可以把 MCP 当成“插座”把技能当成“电器的使用规程”。插座解决通电问题但一个微波炉怎么用、功率多大、什么食材加热多久这是使用规程的事。在我目前的架构里两者是配合关系技能流程里的每个步骤如果需要访问外部系统就通过 MCP 或类似协议调用而技能本身负责定义步骤顺序、判定逻辑和输出规范。如果一个团队的 Agent 应用里已经接了一堆工具但整体行为还是不可控那问题大概率不在工具缺失而在流程编排层。这时优先补技能库而不是继续堆工具。5. 常见问题与排错实录5.1 Agent 总是不主动调用技能怎么办这是群里被问得最多的一个问题。你明明把技能都注册好了结果 Agent 遇到相关任务时还是自顾自地生成结果完全不理会技能。排查顺序我建议这样来先看技能的description是否包含足够的触发关键词。Agent 判断“该不该用技能”基本靠技能描述和当前任务文本的语义匹配。如果你的描述是“代码审查工具”而用户说的是“帮我看下这个 PR 有没有问题”匹配度可能就不够。把描述改得更接近真实用户口吻比如“审查 Pull Request检查代码变更中的 bug、安全问题与风格问题”命中率会高很多。再看registry.json里技能是否被正确加载。我遇到过几次技能文件路径写错Agent 压根没读到注册表。可以在调试日志里看看技能列表是不是完整如果列表里都没有那自然不会被调用。最后检查触发条件。有些技能的triggers设置太严格比如只有pr_created事件才能触发那么普通对话场景里催多少次都没用。建议给这类技能加一个兜底触发条件user_requests_review这类用户显式表达这样至少能保证手动触发可用。5.2 技能输出不稳定、格式漂移明明定义了输出模板为什么模型有时候还是给出五花八门的格式这个问题我研究了很久最后发现两个主要因素。第一个因素是模板中字段含义不清。比如{conclusion}模型可能填“代码总体质量较好”也可能填“通过”还可能填一长段分析。解决办法是给字段加枚举约束在模板注释里写清楚取值范围总体结论: {pass|need_change|critical}同时把可选值在 SKILL.md 里也说明一遍。第二个因素是模型输出的自由度惯性。即使有模板模型在某些代里还是会发挥。我的解决办法是增加一层轻量级校验器用代码对模型输出做强制格式校验不合规就返回错误信息让模型修正。一句话不要让格式稳定寄托在模型自觉上要用程序兜底。5.3 技能内容与场景不匹配或者上下文污染一个技能包如果太大把几十条规则、参考资料全塞进去模型会“消化不良”抓不住核心逻辑。我见过有人的技能从 2KB 膨胀到 200KB最后还是不好用。这是因为模型在推理时只能关注有限的上下文资料太多反而稀释了关键指令。我的建议是技能库遵守“小即好”原则一个技能聚焦一个任务总体积控制在 5KB 参文以内。如果某个任务的参考资料确实很多可以把资料拆成多个技能或者把资料分层——核心规则放 SKILL.md扩展细节放 references只有需要时才加载。上下文污染的另一个来源是多个技能同时被加载。如果 Agent 一次对话里把code-review和api-doc-generator都加载了它们各自的指令会互相干扰。解决方案是在技能的加载逻辑里加互斥规则明确哪些技能不能同场出现或者限定 Agent 每次主任务只加载一个核心技能其余作为辅助。5.4 技能版本冲突与回滚技能库迭代快很容易出现某个技能升级后和一两个特定场景的适配出了问题。我的处理套路是每个技能目录下的变更都要更新SKILL.md里的 version 字段然后在registry.json里记录每个项目的技能绑定版本。实际操作时我会做一张技能与调用方的兼容性对照表技能版本变更摘要兼容性影响1.2.0增加自我检查步骤输出增加审查人备注字段微调 P0/P1 判定逻辑1.1.0增加 Python 检查清单兼容旧版推荐升级1.0.0初始版本—当某个调用方反馈异常时先查它锁定的是哪个版本对比变更摘要基本能快速定位是不是技能升级导致的。出问题严重时我直接在调用方配置里把技能版本回退到上一个稳定版应用立刻恢复然后再慢慢排查差异。另外有个小技巧技能库仓库里每条 commit 信息都带上技能名和变更动机比如“code-review: 增加对敏感信息硬编码的检测”。几个月后回看历史时你能迅速找到某次行为变化的真实原因不需要靠回忆。最后再分享一个小经验技能库的效果很大程度上取决于你“是否愿意把模糊需求变成明确流程”。我最早写技能总想着让模型自由发挥结果输出千奇百怪。后来改成“流程拆好、接口定死、模板卡住、自我检查兜底”这一套组合拳质量和稳定性一下就上来了。动手之前先挑一个你日常重复度最高、最容易被 AI 搞砸的小任务用这套方法固化成第一个技能。一个能用的技能比十个半成品技能有价值得多。等跑通了第一个后面的只是工作量问题不再是方向问题。