一、什么是 Skill？

1.1 定义

Agent Skill（智能体技能）是可复用的任务完成能力单元——它将目标、流程、工具、知识、约束与验收标准进行一体化封装，让智能体能够稳定、标准化地交付任务成果。

可以用人体能力做直观类比：大模型是「大脑」（负责思考推理），工具是「双手」（负责物理执行），而 Skill 是肌肉记忆 + 标准化操作规程 + 安全约束系统，是串联思考与执行的核心载体。

从物理载体层面看，Skill 本质是一个标准化文件夹，内部包含指令文档、参考资料、可执行脚本等资源。AI 加载该文件夹后，即可习得一项原本不具备的特定工作能力。

核心区别于一次性提示词：Skill 支持持久化保存、跨会话复用、迭代优化，能保障多次任务执行的一致性与稳定性，而非单次临时交互。

1.2 为什么需要 Skill？

大模型具备强大的通用推理能力，但存在两个无法原生解决的底层短板，这也是 Skill 存在的核心价值：

• 缺失私域专属知识：团队代码规范、品牌话术指南、内部业务流程、私有业务数据等，均不在模型公开训练数据范围内，模型无法原生知晓。

• 无标准化执行逻辑：即便赋予模型工具调用权限，模型也无法自主确定工具调用顺序、执行阈值、验收标准，容易出现流程混乱、结果不可控问题。

Skill 正是为解决上述两大核心问题而生：将人类的业务经验、流程规范、约束规则结构化交付给 Agent，使其如同查阅官方工作手册一样自主、合规、稳定执行任务。

行业趋势：2026 年，AI 竞争已从「模型参数比拼」全面转向「Skill 工程化比拼」。Skill 不是简单的脚本或插件，而是封装感知-决策-执行-反馈全闭环的可复用能力单元，是 AI 工程化落地的核心分水岭。

1.3 Skill vs Prompt：本质区别

将 Skill 等同于「高级提示词」是行业最普遍的认知误区，二者在底层定位、工程属性上存在本质差异：

对比维度	Prompt（提示词）	Skill（智能体技能）
生命周期	一次性、临时生效，会话结束即失效	长期复用、支持版本化管理与回溯
核心目标	探索性交互、即兴应答，无强制标准	确定性、标准化执行，结果可复现
工程化能力	无结构化规范，难以维护、迭代、协作	可测试、可灰度迭代、支持团队协作管控

核心定论：Skill 管控「这一类任务」的通用能力，Prompt 管控「当前这一次」的临时交互。一次标准化编写 Skill，可跨场景反复调用，保障每次输出结果高度一致。

二、Skill 的格式构成

2.1 标准目录结构

Skill 以独立目录为最小组织单元，采用分层结构化管理，官方标准目录结构如下：

my-skill/
├── SKILL.md          # 必需核心文件：元数据 + 可执行指令
├── scripts/          # 可选目录：可执行代码脚本（AI直接调用）
├── references/       # 可选目录：参考文档、API规范、业务数据表
└── assets/           # 可选目录：模板文件、静态资源、示例素材

各目录详细功能说明：

• SKILL.md（唯一必需）：Skill 的核心载体，由 YAML 元数据（配置信息）+ Markdown 指令正文（执行逻辑）组成。

• scripts/：存放高精度可执行代码，无需AI阅读理解，仅由Agent直接调用执行，规避模型自由发挥误差。

• references/：存放任务执行中需查阅的静态参考资料，如内部API文档、业务规范、决策对照表等。

• assets/：存放固定模板、图片、标准文案等静态资源，用于统一输出格式与样式。

2.2 SKILL.md 文件格式

SKILL.md 是 Skill 的核心，由上下两部分强制组成：YAML frontmatter（头部元数据） + Markdown body（指令正文），二者缺一不可。

2.2.1 YAML 元数据（Frontmatter）

元数据是 Skill 的「身份说明书 + 执行合同 + 配置入口」，核心作用是告诉 Agent：该技能的身份、功能定位、触发场景、环境要求，是技能被识别触发的核心依据。

字段名	是否必填	字段说明	约束规则
name	是	Skill 唯一标识名	最大64字符，仅支持小写字母、数字、连字符
description	是	功能定义+触发场景说明	最大1024字符，需包含场景关键词
license	否	开源/私有许可证信息	填写许可证名称或外部引用地址
compatibility	否	运行环境兼容性要求	最大500字符，注明模型版本、依赖环境
metadata	否	自定义扩展元数据	键值对映射格式，用于自定义标签、权重等

name 强制命名规则（高频易错）

• 仅允许：小写字母（a-z）、数字、英文连字符（-）

• 禁止：以连字符开头/结尾、连续连字符（--）、大写字母、特殊符号

• 强制关联：必须与Skill根目录文件夹名称完全一致

✅ 合法示例：pdf-processing、data-analysis-v2、code-review

❌ 非法示例：PDF-Processing（大写）、-pdf-tool（连字符开头）、data--analysis（连续连字符）

description 专业写法规范

description 是技能触发的核心依据，必须精准定义功能与适用场景：

✅ 优质示例：Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

❌ 劣质示例：Help handle PDF files.（表述宽泛、无触发关键词、无场景定义）

2.2.2 Markdown 正文（Body）

元数据下方的Markdown正文是Skill的核心执行指令，直接决定Agent激活后的行为逻辑。官方建议正文包含以下模块，整体控制在500行以内，冗余资料拆分至references目录：

• 分步骤标准化操作SOP

• 输入/输出标准化示例

• 边界场景、异常情况处理方案

2.3 最简可用 Skill 示例

仅保留必填字段+核心流程，即可生成可直接被Agent识别执行的最简SKILL.md：

---
name: pdf-processor
description: Extract text and tables from PDF files. Use when working with PDF documents or when the user mentions PDFs or document extraction.
---
# PDF 标准化处理流程
## 步骤 1：输入校验
确认用户提供的PDF文件本地存储路径、文件权限、格式合法性。

## 步骤 2：内容批量提取
调用同级scripts/extract.py脚本，批量提取文档内文本、表格、图片资源。

## 步骤 3：结构化输出
按【文本区块+表格JSON+资源索引】固定格式输出处理结果，标注提取置信度。

三、Skill 的工作原理：渐进式加载

为解决大模型上下文窗口过载问题，Skill 采用**渐进式披露（Progressive Disclosure）**核心机制：Agent 不会一次性加载所有Skill的全量内容，而是分阶段按需加载，精准控制token消耗。

完整执行分为三个层级，层层递进、按需激活：

Level 1：发现层（元数据级 | 冷启动）

智能体初始化任务时，仅批量加载所有Skill元数据中的name + description，单技能仅占用约100 token。

核心逻辑：Agent 通过语义解析description，判断当前任务是否与该技能匹配——这是Skill被触发的唯一判定依据，未通过该层级匹配的技能，不会进入后续加载流程。

Level 2：激活层（指令级 | 热加载）

当任务与某Skill的description语义匹配后，Agent 仅将该Skill的完整SKILL.md加载至上下文，单技能指令内容通常控制在5k token以内。

核心作用：让Agent读取标准化执行流程、约束规则、调用要求，明确具体操作逻辑。

Level 3：执行层（资源级 | 运行时）

Agent 根据SKILL.md中的指令，按需加载references参考资料、调用scripts可执行脚本、读取assets静态资源，完成最终任务执行。未被指令引用的资源，不会加载进入上下文。

实测性能优化：采用渐进式加载后，单Skill初始加载token从16000降至500，降幅达96.9%，极大降低上下文占用，提升推理速度。

四、如何写好一个 Skill

4.1 四大核心设计原则

原则一：区分 Skill 与 Prompt

Skill 不是临时对话提示词，而是长期复用、输入输出强约束、可工程化管控的能力模块。正文必须使用模型可精准解析的结构化语言，明确行为边界、禁止自由推演。

原则二：只写入AI无法原生知晓的信息

Skill 的核心是「下达指令」而非「科普原理」。模型公开训练数据中已有的通用知识、基础原理无需重复编写，仅写入私有信息：团队规范、内部流程、私有工具用法、私域数据规则。

原则三：保持单一职责与极简边界

Skill 的能力强度与复杂度无正相关性。职责单一、边界清晰的Skill，更容易被Agent精准触发，执行稳定性更强。上下文是有限公共资源，冗余复杂的Skill会抢占token空间、降低匹配命中率。

原则四：流程脚本化，嵌入决策分支

优质Skill不是段落式描述，而是可机器解析的SOP（标准作业程序）：明确前置条件、执行顺序、分支判断规则、异常兜底方案，让Agent无歧义执行。

4.2 撰写 description：决定技能生死的关键

再次强调：description是Skill被触发的唯一依据，撰写劣质会导致技能完全无法被调用，是Skill设计的重中之重。

标准化写法要点

1. 句式强制：优先使用祈使句Use this skill when...，替代陈述句 This skill does...，直接引导Agent做决策判断。

2. 预埋关键词：将所有可触发该技能的用户关键词、业务场景词全部写入，提升语义匹配命中率。

3. 场景具象化：先明确回答「用户在什么业务场景、输入什么关键词时需要该技能」，再基于答案撰写描述，杜绝宽泛表述。

4.3 优化指令正文：定义执行全流程

被激活后的正文是Agent的操作手册，完整优质正文必须覆盖7大核心模块，形成闭环执行逻辑：

1. 信息澄清：定义必填输入项，缺失关键信息时主动向用户问询，禁止无依据推演。

2. 线性流程：明确步骤先后顺序、每一步的具体执行动作。

3. 决策分支：定义不同输入/状态下的流程跳转规则（如数据为空、格式异常时走分支B）。

4. 工具调用：指定工具名称、调用参数、执行顺序、权限要求。

5. 失败兜底：定义超时、报错、权限不足等异常场景的降级方案。

6. 结果验证：设定输出验收标准、自检规则，确保结果合规。

7. 输出格式：强制定义最终产出的结构、字段、样式、编码规范。

4.4 合理复用 scripts 与 references

• scripts/ 适用场景：需高精度、零自由发挥的确定性操作。如PDF旋转、数据哈希计算、批量格式转换等，直接固化为代码，Agent仅执行不修改。

• references/ 适用场景：需动态查阅的静态参考信息。如公司数据字典、接口文档、合规禁止词表、审批流程对照表等。

五、Skill 编写技巧与最佳实践

5.1 四大任务设计模式

根据任务复杂度选型对应设计模式，避免过度设计：

• 线性流程模式：步骤固定、无分支，适合简单单次任务（如文本清洗、格式统一）。

• 决策树模式：基于明确条件分支跳转，适合分类、审核、判定类任务。

• 循环迭代模式：重复执行直至满足终止条件，适合批量处理、数据遍历类任务。

• 多阶段编排模式：复杂任务拆分为独立子阶段，各阶段有专属输入输出，适合全链路业务流程（如财报生成、工单闭环）。

5.2 模型自由度分级控制

基于任务容错率，精准控制模型推演自由度，平衡灵活性与稳定性：

自由度等级	适用业务场景	指导方案
高	无固定解法、鼓励创新（文案创作、方案策划）	给出核心原则与约束，由模型自主判断执行路径
中	有优选方案，允许局部变通（常规数据分析）	指定推荐主路径，补充可选替代方案
低	强合规、零容错（金融报表、合规审核）	给定精确步骤与参数，禁止任何流程偏离

5.3 高频误区与避坑指南

• ❌ 误区一：Skill 代码/内容越复杂，能力越强
  ✅ 正解：单一职责的轻量化Skill命中率更高、运维成本更低。

• ❌ 误区二：SKILL.md 是写给人阅读的文档
  ✅ 正解：核心受众是Agent，优先保证机器可解析，精简人文科普内容。

• ❌ 误区三：将上千行全能脚本塞入单个Skill
  ✅ 正解：违背分层设计原则，应拆分核心逻辑至scripts，SKILL.md仅保留调用指令。

• ❌ 误区四：简单任务拆分过多微Skill
  ✅ 正解：粒度适中最优，单个Skill统一处理3-5个强关联子任务，避免管理碎片化。

5.4 评测驱动、失败优先迭代法

优质Skill无法一次性编写完成，需通过真实任务迭代生长，推荐行业标准迭代流程：

1. 最小版本上线：仅配置必填元数据+核心执行步骤，快速落地可用版本。

2. 真实场景测试：用生产级任务验证技能触发命中率、执行成功率。

3. 故障定向优化：针对执行失败、触发错误的点位，补充规则与边界处理。

4. 渐进能力补齐：迭代中补充异常兜底、参考资料、输出模板，逐步完善能力。

5.5 团队协作与版本管理

Skill基于文件化存储，天然适配工程化团队管理规范，落地建议如下：

• 将所有Skill纳入代码仓库统一托管，与业务项目版本联动。

• 引入Code Review机制，审核Skill的触发规则、流程合规性、安全约束。

• 通过Git记录全量迭代日志，支持版本回溯、灰度发布、问题溯源。

• 建立团队Skill市场，沉淀通用能力，避免重复造轮子。

六、总结

Skill 是 AI Agent 时代的核心基础能力单元。它不是升级版提示词，而是一种结构化、可工程化、可复用的能力封装范式——将人类脑中的领域经验、业务流程、合规规则，转化为AI可理解、可自主执行、可长期迭代的标准化模块。

掌握Skill编写与设计的核心精髓，可凝练为四句话口诀：

元数据决定触发，指令决定执行，脚本保证精确，迭代决定品质。

从大模型「会聊天」的交互能力，升级为Agent「会做事」的生产力能力，Skill 是不可或缺的核心桥梁。