做过一段时间Agent开发的朋友应该都有这种体会：模型本身能力决定了上限，但真正让Agent“干活靠谱”的，往往是那些藏在背后的技能包。项目标题提到的这个“Agent Skill”，我在实际项目里从摸不着头脑到慢慢形成一套自己的打法，踩了不少坑也攒了不少经验。今天就把这些开发中的使用心得梳理一遍，从Skill到底是什么，到手写一个能用的Skill，再到怎么在项目里真正把它跑起来，一次说清楚。这篇文章适合正在做智能体开发、想提升Agent输出稳定性，或者刚开始接触Skill概念的朋友，内容偏实战，看完可以直接照抄到自己项目里。
1. 先搞清楚：Skill到底是什么，和Agent、函数、插件有什么区别
1.1 Skill在Agent体系里的准确定位
业内对Skill的定义其实不算统一，但主流共识是：Skill是给大模型Agent准备的一套“专业能力包”，用结构化描述加提示词策略等方式，把一类任务的执行方法沉淀下来，让Agent在遇到这类任务时能稳定地按专业流程干活。
我做了一个比较贴合实际的比喻：如果把Agent理解成一个新入职的工程师，那Skill就是公司给他准备的操作手册加话术模板。手册里写清楚遇到什么情况走什么流程、哪些话能说、哪些事必须做、输出格式长什么样。没有手册的Agent，就像一个全靠临场发挥的新人，状态好时能交付，状态差时连格式都对不齐。
在开发中引入Skill最核心的好处，是把“不可控”变成“可控”。裸模型面对一个模糊需求，输入输出全靠猜。但当你给Agent挂上一个定义良好的Skill时，它会先在Skill描述的引导下理解任务边界，再按Skill正文里的步骤逐步执行，最终输出质量会被约束在一个可预期的范围内。
1.2 Skill与传统函数、API调用的本质区别
这一点我踩过坑，刚开始总觉得Skill不就是封装一层函数调用吗？实际上两者的底层逻辑完全不同。
传统函数调用（Function Calling）是确定性的代码逻辑：输入参数、执行计算、返回固定结构的结果。它适合那些逻辑明确、边界清晰的场景，比如算个价格、查个天气、发个请求。
Skill则是半结构化的引导，依赖大模型的推理能力去执行。它不保证每次输出完全一致，但通过规则约束让结果尽量收敛到高质量区间。
我用一个表格来对比更直观：
| 对比维度 | 传统函数/API | Agent Skill |
|---|---|---|
| 底层机制 | 确定性代码执行 | 大模型推理+规则约束 |
| 输入方式 | 结构化参数 | 自然语言描述+参数提示 |
| 执行过程 | 固定逻辑 | 灵活步骤，允许模型自主调整 |
| 输出质量 | 稳定但死板 | 灵活但有波动，需约束 |
| 适用场景 | 明确、重复、强逻辑 | 模糊、复杂、需要专业经验的场景 |
所以在实际项目中，我的经验是：能写函数解决的别硬做成Skill。Skill的价值是在那些传统代码写不透、写不动的场景里发挥的，比如代码审查、需求拆解、文案风格统一、技术方案评审这类事情。
1.3 Skill和Agent的分工关系
很多刚接触的人会问，Skill和Agent到底有什么区别？我直接说结论：Agent是一个能感知环境、做出规划、调用资源、执行行动的目标导向系统；Skill是这个系统里的一个能力单元。
你可以把Agent想成一个工作室，Skill就是工作室里各个工种。一个完整的Agent，可以由多个Skill组成，再加上记忆模块、规划模块、外部工具和模型本体，才能完成复杂的任务闭环。
Agent ├── 大脑（大模型） ├── 记忆（短期上下文/长期存储） ├── 规划模块 ├── 工具集（函数调用/API） └── 技能包（Skill） ├── 代码审查Skill ├── 需求拆解Skill └── 输出格式化Skill我在开发中给团队的指导原则是：先分清楚哪些能力属于Agent的骨架逻辑，哪些能力适合封装成Skill。骨架逻辑（比如任务循环、上下文管理、工具调度）写在框架代码里；而那些“换一个应用场景就要换一套方法”的专业知识，全部抽成Skill。这样当用户从“帮我写个接口”切换到“帮我审查这段代码风格”时，Agent不需要改代码，只需要在技能库里调度对应的Skill就行。
2. 一个标准的Skill长什么样：目录、元信息与描述规范
2.1 从Anthropic Agent Skills格式说起
目前社区里比较流行、也是我一直在用的规范，是参考Anthropic提出的Agent Skills组织方式。它的核心思路是：一个Skill是一个独立的目录，里面至少包含一个SKILL.md文件，所有内容都用Markdown编写，因为大模型对Markdown结构化的信息解析效率极高。
一个典型Skill目录结构长这样：
skills/ └── code-review/ ├── SKILL.md ├── examples/ │ ├── good-feedback.md │ └── bad-feedback.md └── rules/ └── security-checklist.mdSKILL.md是入口文件，Agent在决定是否调用这个Skill时，首先读的就是它。这个文件的开头必须是YAML格式的frontmatter，包含name、description、allowed-tools这几个关键字段。
--- name: code-review description: 对代码变更进行系统性审查，识别安全问题、潜在缺陷、性能瓶颈和风格问题。当用户要求review代码、检查PR、评估代码质量时使用。 allowed-tools: - read_file - search_files - list_directory ---frontmatter里的description写得好不好，直接影响Skill能不能被正确调度。我在项目里反复调整后，总结出几条经验：用动词开头（审查、生成、分析、转换），写清触发场景（当用户要求...时），带上领域关键词（代码、PR、安全、性能），就像给搜索引擎优化页面一样，让Agent在语义空间里更容易匹配到这个技能。
2.2 Skill正文的编写要点
SKILL.md中frontmatter下面的部分，是真正的“技能内容”。我强烈建议包含四块：
第一块是目标与适用范围，告诉模型这个Skill解决什么问题、不解决什么问题。边界清晰能避免模型把Skill用在错误场景。
第二块是执行流程，用有序列表把步骤拆开。这里要注意，步骤不要写得太死板。模型不是机器人，你需要给它决策空间，但主流程必须明确。比如代码审查Skill，我可以要求它先读文件、再列安全检查项、再逐条输出问题、最后给修改建议。
第三块是输出规范，明确告诉模型最终结果用什么格式输出。我最常用的做法是：要求用Markdown表格输出所有发现的问题，并且问题严重级别必须从高到低排序。格式固定了，下游无论是出报告还是继续交给其他Agent处理，都非常顺畅。
第四块是示例与禁忌，这是最容易出效果的部分。给1到2个正例和反例，模型对“不要做什么”的理解速度，比“应该做什么”还快。我在代码审查Skill里明确写了“不要在反馈中使用讽刺语气”“不要忽略低优先级但容易引发故障的边界条件”，实测对输出风格纠正很有效。
写完SKILL.md之后，如果要复用同一套规则做批量处理，可以再补充子文件。比如把常见安全漏洞清单放在rules/下，把真实反馈案例放在examples/下。这样Skill越用越厚，知识积累会更加系统。
3. 开发实战：从0手写两个能用的Skill
3.1 动手做第一个Skill：代码审查技能包
我先讲一个我团队里最常用的代码审查Skill，它的目录是skills/code-review/，我已经在上面写好了frontmatter。再来看正文部分怎么写比较合理：
--- name: code-review description: 对代码变更进行系统性审查，识别安全问题、潜在缺陷、性能瓶颈和风格问题。当用户要求review代码、检查PR、评估代码质量时使用。 allowed-tools: - read_file - search_files --- # 代码审查技能 ## 目标 对给定的代码片段或文件变更进行专业、系统、客观的审查，输出可直接用于改进的反馈。 ## 适用范围 - 适用于Python、JavaScript、Go、Java等主流语言的代码审查 - 不适用于配置文件、文档类变更的整体架构评审 ## 执行流程 1. 读取代码文件，先整体把握代码逻辑 2. 按以下维度逐项检查：安全性、正确性、性能、可读性、可维护性 3. 如果发现安全问题，优先标注并给出修复建议 4. 对每一处问题，必须说明问题所在行号、严重级别、理由 ## 输出规范 - 使用Markdown表格输出，列为：严重级别、位置、问题描述、修复建议 - 严重级别使用P0/P1/P2/P3（P0为必须立即修复） ## 禁忌 - 不使用讽刺或评判性语言 - 不忽略边界条件和异常处理问题 - 不凭空臆断业务需求，只针对代码本身做审查关键点在两步：第一步“先整体把握逻辑”，这是为了让模型先建立上下文，再说具体问题；第二步的维度清单，不是随便列的，是把代码评审里最高频的问题类型做个优先级排序，这样模型在审查过程中不会把精力浪费在无关紧要的细节上。
实际使用时，把这段SKILL.md放进项目目录的skills/code-review/下，在Agent工具中挂载这个技能目录。当用户发来一段代码说“帮我看看这段有什么问题”，Agent会先读取SKILL.md了解工作方法，然后按执行流程去完成任务。
3.2 进阶Skill：JSON Schema校验与修复技能包
第二个Skill更有代表性，它结合了规则校验和模型推理，能解决一个很常见的开发痛点——开发对接第三方API时，返回的JSON数据结构和本地定义不一致，导致程序跑不起来。这个Skill的设计目标是：拿到JSON数据和预期Schema，自动完成校验、定位差异、并输出修复方案或修复后的数据。
这个Skill的SKILL.md我设计为json-schema-repair，它的执行流程比代码审查稍复杂，需要模型在“校验-定位-修复-复验”这个闭环里循环。我在执行流程里加了一个关键判断：如果修复后的数据还是不符合Schema，必须重新回到定位步骤，最多循环三次，仍失败则明确告知调用方无法自动修复。
--- name: json-schema-repair description: 校验JSON数据是否符合JSON Schema，定位不符合字段并生成修复方案。当用户上报数据结构错误、接口返回格式不符、JSON解析失败时使用。 --- # JSON Schema修复 ## 目标 ... ## 执行流程 1. 解析JSON数据和Schema 2. 逐字段校验类型、格式、必填、枚举等约束 3. 对每个差异字段给出修复动作 4. 执行修复并重新校验 5. 循环执行第3-4步，最多3次 6. 输出修复结果报告写这个Skill时我最大的体会是：流程类Skill一定要控制循环深度。如果不加这个限制，模型遇到复杂数据时可能陷入死循环，一遍遍自我修复，浪费大量token。加上“最多循环三次”这个规则，既给了模型尝试空间，又保证了整体执行有尽头。
3.3 Skill文件的组织与版本管理
Skill开发多了以后，最怕的就是“改了一版，不知道之前为什么这么写”。我在实际项目里把每个Skill当成一个独立代码库来管理：
- 每个Skill放在独立子目录，目录名就是技能名，全部小写、用连字符连接。
- SKILL.md是唯一入口，子文件（如rules、examples、templates）按需补充。
- 整个技能集用Git管理，每个技能单独维护CHANGELOG，记录每次行为调整的原因。
这样做最大的好处是可以放心迭代。以前用“一把梭”的方式把Skill内容全塞在一个提示词模板里，参数和逻辑全耦合，改一个规则可能影响所有任务。拆成独立技能包以后，每个技能的改动只影响自身调度场景，其他人接手项目时也能快速定位到具体技能文件。
4. 在开发项目中真正把Skill用起来
4.1 通过本地目录挂载与安装方式引入
如果你用的是支持Agent Skills的工具或框架，最常见的方式是通过环境变量指定技能目录。比如在Claude Code、Cursor这类开发辅助工具里，配置SKILL_PATH指向你的技能目录：
# 在Shell配置文件中设置 export SKILL_PATH="/Users/yourname/workspace/my-agent-skills"配置好之后，开发工具会自动扫描这个目录下的所有Skill，并把每个SKILL.md的frontmatter注入到系统上下文中。当Agent收到任务时，它会根据description字段的语义匹配结果，动态读取对应SKILL.md的完整内容。
我测试过多次，这个机制实际执行效率很高。因为工具只把每个Skill的名称和一句话描述暴露给模型，而不是把全部技能正文塞进上下文。只有模型判定某个技能相关时，才会加载正文。这样即使技能目录里有几十个Skill，也不会把上下文窗口撑爆。
4.2 在LangChain4j等框架中把Skill接入Function Calling
除了开箱即用的开发工具，更多时候我们需要在自己的Agent框架里实现Skill调度。以Java生态的LangChain4j为例，核心思路是把Skill的元信息转化成模型能识别的工具描述，再在tool执行阶段按需加载Skill正文。
ToolSpecification reviewSkill = ToolSpecification.builder() .name("code_review") .description("对代码变更进行系统性审查，识别安全问题、潜在缺陷、性能瓶颈和风格问题。当用户要求review代码、检查PR、评估代码质量时使用。") .addParameter("code", ParameterSpec.builder() .description("需要审查的代码内容") .type(STRING) .build()) .build();在这个方案里，LangChain4j的function calling机制负责把“用户要求审查代码”这样一个意图，映射到code_review这个工具调用上。而工具内部执行时，我们再去读取SKILL.md正文，把内容拼接进发给模型的二次请求里，让模型按技能流程执行。
我自己的经验是，不要把SKILL.md正文也塞进function calling的description里。description太长会影响模型对工具选择的判断，还会多消耗token。正确做法是：description只写关键触发场景，正文在工具实际执行时再加载，这样既能精准调度，又能保留完整的执行规则。
4.3 系统提示词和Skill怎么分工
这是很多人纠结的点，也是搜索热词里提到的问题：系统提示词工程和Skill到底有什么区别、怎么配合使用。
我的理解是：系统提示词是Agent的地基，Skill是地基上的预制件。系统提示词负责定义Agent的整体人格、回答边界、通用工作准则，例如“你是一个严谨的Java开发助手，所有回答必须给出代码示例”。它管的是全局，每轮对话都在生效。
Skill管的是局部任务的高质量执行。只有当任务命中了某个技能场景时，对应的SKILL.md才会被加载。它是按需加载、用完即走，不影响Agent在其他场景下的行为。
在项目里最好的组合姿态是：系统提示词里只写“骨架级”的设定，把关于“如何干好某类活”的细节全部从系统提示词里剥离出来，下沉到Skill里。这样既减轻了系统提示词的长度压力，也让每个技能的迭代不影响整体Agent的表现。
我举一个具体例子。早期我做代码审查功能时，把审查规则全部堆在系统提示词里，结果Agent每次回复都带着一堆审查规则上下文，其他任务也受干扰。后来我把所有审查规则挪到一个Skill里，系统提示词里只留一句“当你需要执行代码审查时，请加载code-review技能”。改动之后，整体回复质量和响应速度都有提升，这就是分工带来的收益。
5. 常见问题与排查技巧实录
5.1 高频问题速查表
下面这几类问题，是我在实际使用Agent Skill时反复遇到过的，整理成一张排查表，方便直接对照：
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
| Agent完全没有调用Skill | description语义与用户意图不匹配 | 重写description，用动词开头、带领域关键词 |
| 每次执行结果差异很大 | Skill正文中步骤约束不足 | 增加强制步骤顺序和输出格式规范 |
| 调用了错误场景的Skill | 多个Skill的description边界重叠 | 为每个Skill明确限定适用范围和禁用场景 |
| Skill加载后仍然乱答 | 正文内容太长，模型忽略了关键步骤 | 把最关键规则前置，用加粗和表格突出 |
| 技能目录没生效 | 环境变量未配置或路径错误 | 检查SKILL_PATH路径权限，并确认目录结构 |
| 在框架中工具调用失败 | function calling参数类型声明不对 | 核对ToolSpecification的参数类型与JSON Schema定义 |
5.2 我在调Skill过程中踩过的几个坑
第一个坑，是description写得太泛。我最早写的一个Skill描述是“帮助用户解决开发问题”，这个描述几乎匹配了所有场景，结果是这个Skill被频繁调用，但每个场景都干不深。后来我把描述改成“对SpringBoot项目的依赖冲突问题进行分析并给出修复建议”，触发精准度一下子提升了很多。Skill描述宁可窄一点，也不要宽泛到没有边界。
第二个坑，是太相信Skill的一次性调教。Skill不是写完就一劳永逸的，它对模型行为的约束效果，会随着模型版本升级而波动。同一份SKILL.md，在GPT-4o上表现很好，换到新模型上可能步骤执行顺序就会变。我的应对策略是隔一段时间就把之前的真实样例跑一遍，看看输出有没有退化，如果退化了就针对性地补强正文。
第三个坑，是忽略了对输出格式的硬约束。早期写Skill时，我只写“请给出审查意见”，结果模型有时候用列表、有时候用段落、有时候用表格，下游解析脚本苦不堪言。后来所有Skill输出段我都强制“使用表格、标明严重级别、按优先级排序”，解析稳定了，整个链路都顺畅了。
第四个坑是关于版本兼容的。我给一个Skill加了新规则，结果发现老版本Agent任务还在用旧逻辑执行，排查了半天才发现是技能目录缓存没有刷新。现在我的做法是：每次改动SKILL.md后，重启开发工具的会话，同时用统一的目录加载，避免多副本同时存在。
被这些问题折腾过几轮之后，我的心态也变了。Skill的开发更像是一个持续打磨的过程，而不是一次性的代码交付。我自己现在每做一个新Skill，都会先拿5到10个真实的用户问题去测试，记录触发率、执行效果、输出格式符合率，然后根据测试结果迭代。这种“数据驱动”的方式来维护技能包，比自己凭感觉改提示词要靠谱得多。
最后再分享一点个人体会：刚开始接触Skill时，很容易陷进“什么都要做成Skill”的冲动里。但做了一段时间你会发现，真正高价值的Skill其实就那几个——你所在的业务场景里最复杂、最重复、最需要专业经验的那几件事，把它们打磨好，就已经能解决80%的效率问题了。Skill不是越多越好，而是越准越好。把一套高质量技能控制在五六个左右，迭代起来既轻松又有效。
