最近一段时间我一直在倒腾各种 Agent 框架市面上主流的方案基本都试了一圈最后意外在一个看起来非常不起眼的小仓库里找到了最顺手的套路——就是标题里这个 agent-skills。说白了它是一套给智能体用的“技能库”通过结构化、人可读的文档来描述一个 Agent 能做什么、怎么按固定流程做配合相应的脚本让大模型在特定场景下直接调用。这招解决了我此前用 Agent 写代码、做数据处理时最头疼的“模型发挥不稳定”问题。如果你也在做 Agent 相关开发或者正在纠结 MCP 是不是万能解药、想让模型在特定领域里稳定输出而不是靠抽卡运气那这篇内容值得你花几分钟读完。我不会讲太多空泛概念直接把我自己的设计方案、目录结构、踩过的坑和最后的维护套路全部摊开来讲。1. 认知重构agent-skills 到底是什么解决了什么问题1.1 传统 Agent 框架的痛点先说我遇到的真实场景。之前我用过不少 Agent 框架核心思路都是给模型一堆工具函数tool让它自己决定先调用哪个、参数怎么填。听起来很美好模型也的确能“自主”干不少事但问题就出在“自主”这两个字上。举个例子我让 Agent 帮我在一个 monorepo 工程里改某个子包的构建配置。模型在思考过程里会先扫描目录结构猜哪个文件对应用途然后直接上手操作。十次里面大概有三四次它会选错配置文件或者用了不符合当前项目规范的旧命令。表面上看是模型能力问题实际上是我们把“工具的存在”和“工具的正确用法”拆开了。传统方式里工具列表只有函数签名和一行 description模型并不知道什么时机该用、是不是有前置条件、上一次踩坑的教训是什么。1.2 一种把“会做”变成“会按规范做”的设计agent-skills 给我最大的认知冲击是它把事情反过来做了。不是给模型一堆“动词”而是给模型一堆“技能文档”。每个技能是一个 Markdown 文件加配套脚本Markdown 里写了非常具体的情境判断、操作步骤、易错点、验收标准。模型在规划任务时会先读这些技能描述然后决定哪条技能最匹配当前任务再按文档里的步骤一步步执行。我习惯用一个比喻传统工具调用相当于给一个实习生一张写着“使用扳手、电钻、卷尺”的清单至于什么时候用扳手、怎么控制扭矩全靠实习生临场发挥而 agent-skills 就像给实习生一本图文并茂的作业指导书不仅写清楚了用哪个工具连拧几圈、用什么姿势、拧完怎么检查都写清楚了。最终效果就是模型表现从“随机应变”变成了“稳定复现”。1.3 适用场景与边界我自己用了这么久的感受是agent-skills 特别适合三类场景第一类是团队内部有既定规范但文档散落各处的项目比如统一的 git 提交格式、代码风格检查命令第二类是高频重复的固定操作比如发布某个子包、生成变更日志、跑特定回归测试第三类是需要保持统一口径的数据处理流程比如从日志里抽取指标、清洗特定格式表格。但它也不是万能的。如果你需要模型实时感知多维状态、动态组合上百个工具那 Agent 框架和 MCP 那套方案仍然有用。agent-skills 更适合那种“把成熟流程固化下来让模型每次按最高标准执行”的场景而不是探索未知方案。2. 核心设计解析为什么技能文件能 work2.1 人类可读的技能定义这个模式里最核心的东西就是 SKILL.md。我最初看到这个文件名还以为是惯例命名后来发现这几乎是社区公认的约定。它的本质就是写给模型和人类共同看的标准文档但写法很有讲究。一份写得合格的技能文档至少应该包含五块内容技能概述一句话说清楚这个技能用来干什么、触发条件什么情境下你才应该调用它、依赖环境需要哪些变量、工具、网络资源、操作步骤拆成编号步骤每步尽量可验证、常见坑把这个技能执行过程中最容易出错的地方提前写出来。值得注意的是文档里不要堆砌 AI 能读但人看不懂的术语。因为这类技能库往往要以团队形式维护把这个仓库 clone 下来的不只是模型还有人。我第一次给团队做培训时把 SKILL.md 打印出来大家都觉得这就是一份非常标准的工作手册——这恰恰是关键只有人觉得清楚明白的规则模型才能真正稳定执行。2.2 工具护具的封装思路光有文档还不够真正干活总得执行命令、调接口。我在实践里采用的是“文档脚本”双件套SKILL.md 用来描述流程scripts/ 目录里放实际执行代码。也许有人会问那跟普通 function calling 有什么区别区别在护具shim。我自己实现的技能脚本通常不是把业务逻辑全包进去而是做一个“带护栏的壳”。比如我写了一个 git 提交技能脚本内部不会让模型自由拼接 commit message而是先检查暂存区是否有文件、是否处于合并状态、分支名是否符合规范最后再按固定模板生成提交信息。模型能自由掌控的只有少量参数其余全部由脚本把关。这样做的核心收益是“限制伤害范围”。模型再强也有概率在细节上翻车护具层把这些概率性失误挡在外面。你甚至可以极端一点某些技能脚本只做校验和转译真正的危险操作仍然需要人工确认。2.3 与 MCP 工具的取舍对比很多朋友一听说工具就联想到 MCPModel Context Protocol问我为什么不直接用 MCP 而是要自己建技能库。我两个都用过做个直观对比维度MCP 工具agent-skills 技能库本质把外部工具接入模型提供一组可调用的 API把流程知识和配套脚本固化进上下文学习成本需要写 MCP server理解协议细节写文档和脚本即可上手快稳定性依赖模型对工具的选择和参数推断通过文档约束步骤稳定性高维护成本接口变更需要同步协议文档和脚本统一管理维护直观适用阶段探索阶段、工具组合多变流程成熟、需要固定复用我的结论是两者不是替代关系而是上下游关系。MCP 能帮我快速接入各种数据源和外部服务但一旦某个流程被我摸透了我就会把它沉淀成技能写清楚步骤和坑让模型以后在这个场景里别再绕弯子。3. 实操落地搭建一个自己的技能库3.1 技能库的项目目录结构先说目录怎么规划。我踩过初期乱放的坑后来吸取教训整理出一套清晰结构用起来非常顺手agent-skills/ ├── README.md ├── skills/ │ ├── git-commit/ │ │ ├── SKILL.md │ │ └── scripts/ │ │ └── commit_with_guard.py │ ├── release-package/ │ │ ├── SKILL.md │ │ └── scripts/ │ │ └── release.sh │ └──>--- name: git-commit description: 在存在分支保护和 lint 检查的仓库中按团队规范创建 git 提交。当模型需要提交代码、生成 commit message 时使用。 ---接着写触发条件和前置要求。我的习惯是写得很“轴”宁可啰嗦也不能含糊## 何时使用 - 需要提交暂存区中的代码变更时。 - 用户要求生成提交信息或推送到远端时。 ## 硬性前置条件 - 必须在 git 仓库根目录执行。 - 必须存在 .git-hooks/commit-msg 配置文件。 - 必须先将需要提交的文件加入暂存区。再往下是具体步骤。我之前写初版时偷懒只写了“使用脚本提交”结果模型真就只执行了一条命令完全没理解内部逻辑。后来我改成在文档里把脚本会做什么、脚本之外的检查有哪些全部写清楚执行git status确认当前分支和暂存区状态。运行scripts/commit_with_guard.py --type 类型 --scope 模块 --message 简述。脚本内部会检查分支名、暂存区文件列表、commit-msg 钩子是否生效。提交成功后运行git log -1 --oneline验证结果。最后一定要写常见坑。我自己写的常见坑包括“分支名带 feature/ 前缀时提交信息要自动补充编号”“暂存区为空时脚本直接退出不要尝试强行提交”“如果 commit-msg 钩子报错不要绕过它必须修复钩子检查项”。写完之后脚本的内容我放在代码块里简单示意#!/usr/bin/env python3 import argparse, subprocess, sys, re def main(): parser argparse.ArgumentParser() parser.add_argument(--type, requiredTrue) parser.add_argument(--scope, requiredTrue) parser.add_argument(--message, requiredTrue) args parser.parse_args() branch subprocess.check_output([git, branch, --show-current]).decode().strip() if not re.match(r^(main|develop|release/.|feature/.)$, branch): print(分支名不符合规范禁止提交, filesys.stderr) sys.exit(1) staged subprocess.check_output([git, diff, --cached, --name-only]).decode().strip() if not staged: print(暂存区为空请先 git add, filesys.stderr) sys.exit(2) # 拼装提交模板 subject f{args.type}({args.scope}): {args.message} subprocess.check_call([git, commit, -m, subject])你可以看到脚本本身不复杂但它把提交动作限制在一个安全轨道内分支名不合法不给提交暂存区为空主动报错提交信息模板化。3.3 在对话上下文里调用技能的正确姿势目录和文档都准备好了接下来说怎么让模型真的读到这些内容。我在实际项目里并不是让模型自己去文件系统翻技能目录而是在系统提示词system prompt里维护一份“技能索引”把每个技能目录名、一句话描述、适用场景列出来。模型在做任务规划时看到索引就会自行决定要不要查看对应 SKILL.md。比如系统提示词里会有这么一段以下技能可用请根据任务类型选择。查看技能的方式是读取对应 SKILL.md 文件 - git-commit安全提交代码生成规范提交信息 - release-package发布 npm 子包自动处理版本号与变更日志 ->import pathlib SKILL_ROOT pathlib.Path(__file__).resolve().parent.parent同理依赖环境也要在 SKILL.md 里写明。模型读文档时如果发现需要 Python 3.11 或某个环境变量就会在调用前先检查环境如果你不写模型大概率会直接跑脚本然后报出毫无头绪的错误。4.2 模型读不到技能内容的坑刚开始用这套方案的朋友最容易遇到的现象是所有文件都建好了技能索引也写进系统提示词了但模型就是不调用技能而是自己即兴发挥。我排查下来九成原因是技能描述写得没有辨识度。比如有个技能叫“代码审查”描述是“对代码进行审查”。这跟模型自己会做的事完全重叠模型自然觉得没必要读文档。后来我改成“对 MR 变更按团队规范进行审查自动检查测试覆盖、提交规范与遗留 TODO并输出结构化审查意见”模型立刻知道“哦这个技能有额外信息值得加载”。4.3 工具被滥用的坑护具再强也挡不住模型在某些场景下“乱开技能”。我遇到过一次模型在清理临时文件时调用了发布技能完全是误伤。后来我整理了触发条件每条都加上了“绝对不要使用”的负面清单## 禁止使用 - 当且仅当用户明确要求发布包时才使用。 - 任何清理、删除、重构任务一律禁止调用。这个负面清单效果出奇的好。模型在不确定的边缘场景中更容易遵循“禁止条款”反而比“允许条款”更能约束行为。4.4 常见问题速查表现象可能原因解决方案模型不调用技能描述不清晰技能索引过载精简描述加负面清单脚本在本地正常但 CI 失败依赖相对路径改为绝对路径参数传入文件路径技能执行到一半卡住缺少前置条件检查在 SKILL.md 中写明硬性前置条件模型选了相似技能多个技能描述重叠合并技能或明确区分适用边界文档更新后旧脚本报错版本不同步SKILL.md 与 scripts 在同一个版本中提交5. 进阶玩法与后续扩展5.1 把技能库做成团队基础设施一旦尝到了技能库的甜头你就会自然想把它推广成团队基建。我的做法是专门建一个 agent-skills 仓库然后通过 git submodule 挂到相关项目里。各项目的系统提示词只维护简短索引真正的流程知识都下沉到技能库。这么做的好处是团队里任何成员或者任何使用 Agent 的流程都能依赖同一套规范。新人来了也可以直接读 SKILL.md 快速了解“这个项目要怎么提交代码、怎么发版”等于顺带解决了文档沉淀问题。5.2 结合持续集成自动生成技能摘要这里分享一个我最近在研究的技巧技能索引不用手动维护可以用持续集成流水线自动生成。我写了一个小脚本扫描技能目录下所有 SKILL.md 的 frontmatter自动汇总成索引文件然后提交到仓库。这样团队成员新增技能时只需要写好 SKILL.md 开头三段信息索引会自动更新避免“技能上线了但模型不知道”的尴尬。5.3 从技能库延伸到工作流如果你觉得这套模式顺手还可以继续延伸到“工作流”层面。技能是一个个原子操作工作流则是一串有序技能的组合。比如“发布新版本”这个工作流可以拆成“更新版本号”技能、“生成变更日志”技能、“跑回归测试”技能、“打 tag”技能。模型按顺序执行这些技能中间每个步骤都有护具兜底整体可靠性比一次性自由发挥要稳得多。我自己目前的项目架构就是“Agent 管规划技能库管执行”。规划层可以随便用那些聪明的模型执行层则被技能文档和护具脚本约束得死死的。这样组合下来我在实际运行中的成功率比我早期纯靠提示词灌规则的时候提升了几个量级。5.4 最后分享一个维护心得关于 agent-skills 这套玩法我最大的心得体会是千万不要把它设计成一劳永逸的规则引擎它应该是一个动态演化的过程资产。我的做法是每两周做一次技能库复盘把模型最近失误的操作案例整理出来如果是某个技能的边界没说清就补边界如果是脚本护具没拦住就加强护具。用真实失败反哺文档这套体系才会越用越准。如果你只是把技能写完之后丢在那儿不管三个月后它大概率已经跟实际项目脱节了。另外奉劝一句技能数量宁缺毋滥。真正有价值的核心技能通常只有十几个剩下的都是在堆垃圾。把每个技能写得像教科书一样严谨比写几百个水技能有用得多。希望这篇经验能帮你在 Agent 落地的路上少走一些弯路。