agent-skills实战：从零打造可复用、可验证的AI Agent技能包

如果你最近半年一直在跟AI Agent打交道，大概率会注意到一个越来越高频的词：agent-skills。我最初接触这个方向时，心里其实有点嘀咕——这不就是把一堆prompt和脚本打包起来吗？后来真把一个小技能从零写好、挂进Agent、跑通一轮完整任务之后，才发现这里面的门道远比“提示词模板”深得多。今天这篇就把我对agent-skills的理解、设计思路、实操过程以及踩过的坑一次性说清楚。

这篇文章适合正在做Agent应用、想给Agent扩展能力边界，或者已经在用function calling但觉得长尾场景越来越难维护的开发者。无论是做编码助手、智能客服、自动化流程，还是个人知识库Agent，只要你想让Agent拥有“可复用、可验证、可跨场景迁移”的稳定技能，agent-skills这套思路都值得仔细过一遍。

1. agent-skills到底在解决什么问题：从一次性提示到可复用技能包

1.1 function calling覆盖不了的“长尾场景”

传统上给Agent加能力，最主流的方法是function calling：定义好函数名、参数结构和描述，模型在需要时发起调用。这个模式简单直接，但有一个很尴尬的边界——它适合“单次、边界清晰、参数明确”的操作，比如查询天气、创建工单、计算运费。可一旦任务变成“把一个仓库里的代码全部读一遍，输出健康度报告”，事情就开始变味了。

这类任务没有单一函数能包裹，它需要好几轮工具调用、上下文汇总、规则判断，而且不同仓库的代码结构还不一样。如果硬塞进function calling，要么函数定义长得像一本书，要么只能靠模型在system prompt里自由发挥。我最早做代码审查类Agent时就是这种状态：prompt越来越长，召回率的波动越来越大，换一个框架又要重新调一遍，痛苦到怀疑人生。

这时候agent-skills的意义就出来了。它把“完成某类任务所需的知识、指令、脚本和校验逻辑”打包成一个整体，Agent按需加载，用完即走。核心思路不是给模型更多函数，而是给模型一组“能力的配方”——模型知道什么时候该用这个配方，也知道配方里每一步该怎么做，而不是靠临场瞎猜。

1.2 prompt为什么解决不了“能力的沉淀”

也有人会说：这类任务我用精心设计的prompt也能让Agent完成，为什么非要搞成技能包？我承认，在单次调用里，一段写得好的prompt确实可以发挥很大作用。但把时间线拉长，问题就暴露了。

首先是上下文膨胀。一段高质量的长prompt可能有两三千字，如果同时挂10个技能，光技能指令就能占掉小半上下文窗口，留给真正任务内容的token所剩无几。其次是版本失控。prompt改来改去没有版本概念，今天还能跑，明天加了几句话就废了，出了bug也不知道该回滚到哪里。最后是无法验证。普通prompt是给模型“看”的，没有结构化校验，模型理解歪了、参数漏了，你只能靠肉眼观察输出结果来推断哪里错了。

agent-skills的思路是把这些混沌状态结构化和工程化：通过frontmatter做元信息管理，通过正文做行为约束，通过引用文件和脚本做确定性逻辑，通过有限状态验证保证技能本身可用。它把我以前靠“在prompt里反复叮嘱”的方式，变成了“在包的层面设定边界和出口”，让Agent的行为可预期、可调试、可回滚。

1.3 技能包的本质：三种内容的组合

我后来想明白一件事：agent-skills本质上是在一个目录里，把三类内容组合成一个自洽的单元。第一类是“做什么”，也就是技能的意图和适用条件，让模型判断什么时候该启用这个技能；第二类是“怎么做”，包括具体指令、流程步骤、输入输出格式，甚至一些示例；第三类是“核心逻辑”，也就是真正执行时需要用到的脚本、配置和参考文件。

这三类内容各有各的形态，而它们之间靠一个统一的“说明书”来索引和调度。这个目录就能独立于主应用存在，可以被复制到任何支持该规范的Agent环境里。我之所以喜欢这个结构，是因为它把“变化的部分”（提示词和规则）和“稳定的部分”（代码和配置）拆开了，迭代起来非常舒服。

2. 技能包的核心设计：SKILL.md如何撑起一个可复用技能

2.1 为什么用Markdown而不是JSON或纯代码

第一次看到SKILL.md的时候，我的第一反应也是：为什么核心文件用Markdown？用JSON不是更容易解析吗？后来在实战里我才明白这个选择的精妙之处。

JSON虽然是结构化数据，但它只适合承载元信息和参数定义，很难优雅地容纳长文本指令、流程图、多轮交互示例。你把一段2000字的操作指引塞进JSON字符串里，写起来痛苦，读起来更痛苦。而纯代码呢，对Agent的理解要求太高，模型需要在代码注释和分支逻辑里去“揣摩”技能意图，损耗很大。

Markdown恰好卡在中间：frontmatter部分提供机器可读的元数据，正文部分提供模型可读的自然语言指令，代码块和引用部分又能挂钩外部脚本和参考文件。Agent读它的时候，既能快速解析属性，又能自然理解行为意图。这是一种“人机双读”的设计——人类维护时读起来清晰，Agent加载时解析也稳定。

2.2 frontmatter里的关键字段和设计考量

一个规范的SKILL.md，开头通常是YAML格式的frontmatter。这些字段看起来简单，但每一个背后都有坑。

第一个是name。这个字段不只是给Agent看的标识，还决定了技能在对话中如何被唤起。我建议用连字符分隔的短横线命名，比如code-review-helper，不要用空格或中文，避免在不同Agent框架之间出现解析不一致。

第二个是description，这是整个技能文件里最关键的字段之一。Agent通常靠扫描所有已挂载技能的描述来判断何时调用哪个技能，描述写得太泛，Agent会在不相干的场景里反复误触发；写得太窄，又会导致该触发的时候漏触发。我的经验是：描述里必须包含“触发条件”“适用对象”“能带来的结果”三个要素。比如“当用户要求对本地或远程代码仓库进行健康检查、质量评估、缺陷梳理时使用，输出结构化报告”，这个描述就比“用于代码审查”精确得多。

第三个是version和license。Version用于标记技能包版本，配合更新机制可以做增量升级；license则决定了技能包能否被安全地跨团队、跨项目共享。这些字段不直接影响Agent行为，但直接影响工程管理，建议从一开始就养成填写的习惯。

2.3 正文的“渐进式披露”原则

技能正文怎么写，决定了这个技能在长任务中的稳定性。很多新手会把所有步骤、所有规则、所有示例一股脑堆进去，结果Agent在每一步都需要处理巨量上下文，反而更容易出错。我采用的是一个被验证过多次的原则：渐进式披露（progressive disclosure）。

简单来说，就是在技能文件的顶层只放最核心的意图、执行流程和关键约束，让Agent“大概知道要做什么”。具体的细则、规则表、错误码、配置模板，统一放到references目录下的独立文件里，通过相对路径引用。当Agent进入某个具体阶段时，再去加载对应的参考文件。这样既保证了初始指令的精简，又保留了深入处理复杂任务所需的全部细节。

举个例子，我写代码仓库体检技能时，SKILL.md正文里只定义了四步流程：扫描结构、分析依赖、检查常见问题、生成报告。至于每一类问题对应的具体规则和严重级别，全部放在references/code-smells.md和references/rules.yaml里。Agent在日常简单场景中只需要读取主文件，遇到复杂情况时才按需打开细粒度规则，上下文消耗节省了至少40%。

2.4 示例与“负向示例”的价值

技能包里必须有一组示例，但很多人只放“正确答案”，却忘了放“错误示范”。我在调试中发现，负向示例对模型的纠偏效果极其显著。原因很简单：语言模型在少样本场景下，不仅会模仿正确的路径，也会通过排除法理解什么情况不应该触发某个操作。

我的做法是，在每个技能目录下建一个examples目录，里面放三到五组输入输出对，且每组都明确标注“这是一个合格的输出/这是一个不合格的输出”。不合格的案例一定要写明原因，比如“缺少严重级别字段”“未调用依赖分析脚本”“跳过空值检查”。这比在正文里写十遍“你必须注意”都管用。

3. 加载机制与上下文管理：让技能包真正进入Agent的决策链路

3.1 按需加载：从“全程在场”到“随叫随到”

如果所有技能都被一次性塞进Agent的上下文，那我们回到原点——上下文爆炸、无关技能互相干扰。所以成熟的agent-skills方案都会引入按需加载机制，核心思路是延迟绑定：技能描述先以极低成本进入模型的可见范围，真正执行时再把技能全量内容注入。

有一个点很容易忽略：技能的调度判断本身也在消耗token。如果一个技能的描述就写了大几百字，Agent在判断“要不要用”时就已经很不经济了。所以我始终强调，description要精炼，让人和模型都能一眼看明白这个技能的边界。在某开源实现里，加载器在运行时只将“技能名称+描述”拼入候选列表，直到模型明确选择了某个技能，才读取该目录下完整的SKILL.md和引用文件。这套机制我复刻到自己的项目里后，整体上下文消耗下降了大概三分之一，而且误触发率也显著改善。

3.2 挂载机制与白名单权限控制

技能包不是说放进去就完事，它需要一套挂载（mount）逻辑。挂载点可以理解成“该技能在Agent工作区中的可见路径”，比如将技能中scripts目录映射到一个可执行目录，将references目录映射到只读知识目录。

这个设计带来的好处很实在：权限边界清晰。技能包里的脚本是否允许执行，哪些文件允许读写，都可以通过挂载配置严格控制。我曾经遇到过一个技能包，因为挂载时给了过宽的写权限，脚本在跑数据清洗时把原始数据给改了，好在有版本控制才救了回来。从那以后，我在所有技能包的挂载配置里默认只给temp目录写权限，需要持久化的输出统一重定向到指定工作目录。

3.3 技能与MCP的协同分工

在Agent工程里，常有人把agent-skills和MCP（模型上下文协议）混为一谈，其实它们的定位完全不同。MCP解决的是“如何连接外部系统和数据源”的问题，面向的是实时服务；agent-skills解决的是“如何让Agent学会一项复杂任务”的问题，面向的是可复用能力。

我在项目中经常同时使用两者：MCP负责连接代码托管平台、数据库和工单系统，agent-skills负责定义“代码体检”“变更影响分析”“发布说明生成”这些偏决策和编排的能力。技能脚本内部需要调用远程API时，再通过MCP通道出去。两者是协同关系，不是替代关系。给技能配外部依赖时，我会特意在SKILL.md里写明“本技能可选依赖MCP工具xx”，这样加载器可以自动做依赖检查。

3.4 清理与释放：技能会话结束后的收尾

技能用完之后的收尾，远比很多人想象的重要。如果Agent在长会话里加载了多个技能，而每个技能的中间文件、临时脚本、缓存数据都留在工作区，几次任务跑下来，工作区会变成一个堆满垃圾的大仓库，还会影响后续任务的判断。

我在设计技能模板时，强制要求每个技能都包含一个cleanup步骤。这个步骤可能是删除临时目录、清理环境变量、或者将中间产物归拢到统一目录。这个习惯起初是出于卫生考虑，后来发现它还顺带解决了一个很隐蔽的问题：技能A留下的临时文件，可能被技能B错误地当成输入数据，导致诡异的执行结果。早一些收尾，就能少很多半夜起来查日志的体验。

4. 从零实现一个技能包的完整实操：以“代码仓库体检”为例

4.1 场景与目标定义

为了把前面讲的理论落到地上，我带大家完整走一遍技能包的制作流程。我们用“代码仓库体检”（repo-health-check）这个技能做例子，它要完成的工作是：分析一个本地或远程Git仓库，检查项目结构合理性、依赖安全状态、常见代码坏味道和提交历史健康度，最终输出一份结构化报告。这个技能覆盖了“读取代码结构—执行静态分析脚本—汇总规则判断—生成报告”多个环节，很适合当作技能包的标准案例。

在动手前，先确定技能包目录结构。我习惯用清晰的分层：

repo-health-check/ ├── SKILL.md ├── scripts/ │ ├── analyze.py │ └── report.py ├── references/ │ ├── code-smells.md │ └── rules.yaml └── examples/ ├── good-report.md └── bad-report.md

4.2 SKILL.md的完整写法与逐段解析

下面是SKILL.md的一个核心骨架，我逐段做注释。

--- name: repo-health-check description: 当用户要求对Git仓库进行健康检查、质量评估、代码体检、依赖安全分析时使用。 适用于本地目录或远程仓库URL。输出包含结构、依赖、代码质量和提交历史的四维报告。 version: 1.2.0 license: MIT metadata: author: dev-core requires: python3, git --- # 代码仓库体检 你的任务是对指定Git仓库执行一次全面的健康检查，最终输出结构化Markdown报告。执行前必须确认目标仓库路径可读，且包含.git目录。 ## 执行步骤 1. 扫描仓库基本信息：分支、最近提交时间、提交总数、参与人数。 2. 运行依赖分析脚本：检查依赖锁定文件是否存在，解析已知问题版本。 3. 检查常见代码坏味道：圈复杂度异常、函数过长、存在重复代码块。 4. 汇总生成报告：按严重级别输出问题清单，并给出改进建议。

我在frontmatter里故意加入了requires字段，用来声明外部依赖。加载器可以据此提前检查环境，避免技能执行到一半才发现缺依赖。description里明确写明了触发场景、适用范围和输出内容，这样Agent在调度时基本不会迷路。

4.3 辅助脚本的设计要点

脚本部分很多人会忽略一个原则：脚本职责单一。analyze.py只负责从仓库里采集数据并输出JSON中间结果，report.py只负责把JSON转换成最终Markdown报告。这样拆的好处是每个脚本都可以单独测试，而且未来如果要换报告模板，完全不需要动采集逻辑。

# scripts/analyze.py 核心片段（示意） import subprocess, json, sys, os def get_git_log(repo_path): result = subprocess.run( ["git", "-C", repo_path, "log", "--oneline", "-n", "200"], capture_output=True, text=True, timeout=30 ) commits = [line.split(" ", 1) for line in result.stdout.strip().split("\n") if line] return {"total_commits": len(commits)} def check_dependencies(repo_path): lockfile = None for name in ["package-lock.json", "pnpm-lock.yaml", "poetry.lock"]: if os.path.exists(os.path.join(repo_path, name)): lockfile = name break return {"lockfile_present": bool(lockfile), "lockfile_type": lockfile} if __name__ == "__main__": repo_path = sys.argv[1] output = {} output["git"] = get_git_log(repo_path) output["deps"] = check_dependencies(repo_path) print(json.dumps(output, ensure_ascii=False, indent=2))

这里有一个我踩过坑的细节：subprocess调用git命令一定要设置timeout，否则碰到超大仓库时脚本会挂在那里，Agent的整个调用链都会被拖死。timeout的取值也要区分场景，本地仓库用30秒通常够用，远程操作则要考虑网络延迟单独设定。

4.4 报告生成与规则引用

报告脚本我一般用Python字符串模板来做，而不是硬编码拼接。原因是硬编码一旦修改格式，很容易破坏其他测试。report.py会读取analyze.py输出的JSON，然后按规则分段渲染。要注意的是报告里的“改进建议”部分应该尽量从references/rules.yaml里读取，避免脚本里到处散落魔法字符串。

# references/rules.yaml 片段 severity_levels: - critical - warning - info rules: - id: S001 pattern: "function length > 100 lines" severity: warning suggestion: "将长函数按职责拆分，提取独立小函数" - id: S002 pattern: "missing lockfile" severity: critical suggestion: "提交依赖锁定文件，确保可复现构建"

这么做有个非常实际的好处：规则文件可以热更新，不用改动脚本本体。我经常在下班前把当天发现的新规则加进rules.yaml，第二天技能就跑得更稳，这种感觉相当不错。

4.5 验证、调试与迭代闭环

技能写完之后不要直接上生产，先做一轮“有限状态验证”。我习惯依次检查几个点：frontmatter字段是否完整、引用路径是否真实存在、脚本在空仓库和仓库两个场景下的返回表现、示例输出是否符合schemas要求。这些检查完全可以做成一个独立脚本，放进项目的toolbox目录里。

验证跑通后，我建议先用真实的小仓库做一次端到端测试，记录Agent实际加载技能时的行为路径。如果发现它在中间某一步停了或者跳过了脚本调用，多半是SKILL.md里的步骤描述不够明确。这时候不要着急改脚本，先改描述，让模型的决定路径更顺滑，然后再重跑验证循环，通常两三轮就能稳定下来。

5. 常见问题与排查技巧实录

5.1 技能没有按预期被触发

这是最常遇到的问题：Agent明明已经挂载了技能，但用户提问时它就是不调用。我排查这类问题时按优先级看三个位置。

先看description是否明确。太泛的描述是头号嫌疑犯，比如“用于代码分析”就远远不够。再看调度候选列表里是否还有其他技能描述更匹配。多个技能存在竞争关系时，模型常常选错。最后看上下文里是否有临时性指令干扰。我遇到过一次，因为用户在对话里说了一句“随便看看”，Agent就把后续所有请求归类为闲聊，技能全程静默。这种情况只能引导用户重新描述需求，或者在技能描述里加上更精确的“当出现关键词x/y/z时必须使用本技能”。

5.2 技能执行到一半中断或报错

脚本执行中断的原因，排名第一的是依赖缺失。很多技能脚本依赖第三方库，而Agent运行环境里根本没装。解决办法有两个：一是在SKILL.md的requires字段里写清依赖，二是把脚本改造成纯标准库实现。我倾向于后者，因为减少外部依赖意味着减少意外。但有时候用标准库实现的代码复杂度太高，那就在技能包附一个bootstrap脚本，在首次调用时自动检查并安装依赖。

排名第二的原因是路径问题。技能脚本在Agent工作区里的实际运行路径，和开发时的路径很可能不一样。最简单的规避方法就是所有脚本用相对当前工作目录的方式解析路径，统一通过一个环境变量来定位技能包根目录，不要硬编码绝对路径。

5.3 上下文窗口还是被撑爆了怎么办

如果你已经做了按需加载，但技能执行到后期上下文还是逼近上限，那大概率是技能运行过程中向上下文写入了太多中间结果。我的解决办法是在脚本层面做“信息压缩”：analyze.py只输出关键指标，而不是把完整日志全部输出。详细的调试日志写进临时文件，不进上下文。报告数据也尽量用紧凑格式传输，最后再统一渲染成可读内容。

5.4 常见问题速查表

5.5 技能包版本管理的一点体会

技能包不是写完就归档的东西，它更像一套持续迭代的协议。我强烈建议把技能包当作独立Git仓库管理，每次修改都要更新version字段和CHANGELOG。这样Agent加载时可以感知到技能版本，后端也能追溯某次异常结果对应的是哪个版本的技能。配合一个简单的manifest.json记录所有可用技能包的元信息和路径，整套工程在技能数量超过5个后会异常省心。

写在最后的个人实操体会

如果你现在正准备在自己的Agent项目里引入agent-skills，我个人建议从小处做起，别一上来就想做一个覆盖全流程的“超级技能”。先找一个你最高频处理、规则明确、重复性强的任务，比如“生成周报”“梳理Changelog”或“做依赖体检”，把它做成一等公民的技能包，跑上两周，你会直观感受到上下文消耗的变化、输出质量的稳定性和调试效率的提升。

另一个很实际的建议是：技能包里的文本指令，尽量用“步骤+验收标准”的结构，而不是“你应该做到……”的模糊要求。Agent是非常擅长遵循清单的，给它清晰的步骤和每个步骤的完成定义，它回馈给你的稳定程度会远超预期。

agent-skills这个方向，大概会是接下来Agent工程里非常重要的基础能力之一。早点把技能包这套工程习惯建立起来，往后再面对各种复杂的Agent任务，你会轻松非常非常多。