从 Prompt 工程到 Skill 工程：一文讲透 Agent Skill 的原理与实践

参考来源：阿里云开发者「Harness 工程之道：Skill 原理与最佳实践」

大模型每轮对话都是"失忆"的，必须从零构建上下文。传统 Prompt 工程将所有领域知识塞进提示词，项目越复杂、Prompt 越臃肿，关键信息被稀释、复用性极低。Agent Skill 以模块化、可复用的文件夹形式封装领域知识，通过渐进性披露按需加载，用最小上下文成本换取最大知识覆盖。本文从原理出发，结合完整实操示例，讲清 Skill 的结构、触发机制与工程化最佳实践。

一、为什么需要 Skill？—— 从"全量灌输"到"按需激活"

大模型会话的核心矛盾在于：每轮对话都是独立的，模型没有持久记忆。CLAUDE.md 等方案将团队技术选型、编码规范固化为 Agent 可读的配置文档，每次会话自动加载，让 Agent 直接进入高效协作模式。

但随着项目规模增长，这种"全量灌输"的模式暴露出三个核心痛点：

1. 上下文膨胀：项目越复杂，Prompt 越长。上下文窗口被无关信息占满，模型的注意力被稀释——真正关键的信息反而被"淹没"在大量背景文本中。
2. 耦合严重：领域知识与具体项目深度绑定。同样是订单查询逻辑，在电商项目写一遍，换到 ERP 项目又得从头再来，复用性几乎为零。
3. 维护成本高：单文件扁平的 Prompt 随着规则增多，增删改查都需要修改一整块文本，稍有不慎就引入冲突。

Agent Skill 的方案是：将领域知识和工作流封装为可移植、可版本控制的文件夹，Agent 在需要时才加载——按需投放知识，而非全量灌输。

Skill 是给 AI Agent 的「入职指南」——新员工不需要第一天背下整本手册，遇到具体任务时查阅对应章节即可。

Skill 与 System Prompt 的分工

简单记法：System Prompt 是"这个项目的规矩"，Skill 是"一种可复用的能力"。

二、核心设计理念：渐进性披露

Skill 最核心的设计哲学是渐进性披露（Progressive Disclosure）——只在需要时加载需要的知识。这与传统"全量加载 System Prompt"的思路形成鲜明对比。

经济学优势：假设有 20 个 Skill，每个完整加载需 3000 tokens。全量加载需 60,000 tokens，而渐进性披露在 Discovery 阶段仅需 1,000 tokens（20 × 50）。大部分请求中真正被激活的 Skill 仅 1-2 个——上下文成本降低一个数量级。

更关键的是，更小的上下文意味着更少的噪音，模型的注意力更集中，决策精准度反而更高。

三、Skill 的结构规范

一个 Skill 就是一个包含SKILL.md的文件夹：

my-skill/ # 必需：skill 名称（小写字母+数字+连字符） ├── SKILL.md # 必需：入口文件（全大写文件名） ├── scripts/ # 可选：可执行脚本 ├── references/ # 可选：参考文档 ├── assets/ # 可选：模板、资源文件 └── ... # 任意额外文件

这种格式已被 Claude Code、Cursor、GitHub Copilot、Gemini CLI 等 40+ Agent 产品采纳，形成了事实上的开放标准（详见 AgentSkills.io）。

3.1 SKILL.md：唯一入口与触发器

SKILL.md分为两部分：YAML frontmatter（元信息）和正文指令（路由表 + 规则）。

---name:order-query-skilldescription:>为用户提供订单查询与操作能力，支持按订单号查询、 按用户ID查询历史订单、订单状态追踪等。 触发词：查订单、订单状态、历史订单、物流查询。argument-hint:"[订单号] [查询类型]"disable-model-invocation:falseuser-invocable:trueallowed-tools:[Read,Grep,Glob,Bash(sql:read)]model:qwen-plusversion:1.0.0---

核心 frontmatter 字段说明：

3.2 SKILL.md 正文：路由器，而非知识仓库

正文应控制在500 行以内（约 2000-3000 tokens），核心职责是路由分发：

## 意图路由表 | 用户意图 | 路由模块 | 加载文件 | |----------|----------|----------| | "查订单" | query | modules/query/query.md | | "查物流" | logistics | modules/logistics/logistics.md | | "退款操作" | refund | modules/refund/refund.md | ## 全局安全红线 1. 禁止直接操作数据库写操作 2. 禁止编造订单数据 3. 退款操作需二次确认

拆分时机：当单个文件超过 300 行，或某个 Step 的规则超过 100 行，就是拆分信号。越频繁用到的知识离入口越近，越偶尔查阅的知识越往深处放。

四、触发机制：description 是灵魂

Skill 支持两种触发方式，互补使用：

• 自动触发：Agent 将用户意图与各 Skill 的description做语义匹配，命中后自动加载。用户无感，如同老员工听到需求就翻出了对应的 SOP。
• 手动触发：用户通过斜杠命令（如/order-query）显式调用，给高级用户精确控制权。

4.1 description 书写公式

公式：功能定义 + 触发场景 + 核心能力。

写好 description 需要遵循以下原则：

1. 同时回答 WHAT 和 WHEN：不能只说"处理订单"，要明确写出这个 Skill 做什么、在什么场景下该被调用。
2. 枚举具体触发词：Agent 做语义匹配时，关键词越具体命中率越高。显式列出用户可能说的所有表达——不只是术语，还包括口语化说法。“查订单”、“订单在哪”、“看看买了什么”、“物流到哪了”——这些都要写进去。
3. 使用第三人称：description 会被注入系统提示词，应写成客观描述。“提供订单查询能力”，而非"我可以帮你查订单"。
4. 划定排除边界：明确写出不适用场景，降低误触发概率。

对比示例：

4.2 作用域与优先级

当多个 Skill 的 description 同时匹配用户输入时，优先级规则为：

全局配置 > 用户配置 > 项目配置 > Plugin 内置

这一层级设计确保了企业级安全策略始终优先于个人偏好。

五、实操：从零构建一个订单查询 Skill

以下以阿里云百炼平台 + 通义千问模型为例，演示完整构建流程。

Step 1：初始化目录

在 AI 对话中直接告诉 Agent：

“帮我用 skill-creator 生成一个名为 order-query 的 Skill”

AI 自动运行初始化脚本，生成标准目录：

order-query/ ├── SKILL.md ├── scripts/ └── references/

Step 2：编写 SKILL.md

---name:order-querydescription:>提供订单查询、物流追踪与退款操作能力。 当用户提到查订单、订单状态、物流、快递、 退款、退货、买了什么、历史订单时触发。 不适用：商品上下架、价格修改等运营操作。argument-hint:"[订单号或查询意图]"version:1.0.0allowed-tools:[Read,sql:read]---

正文路由表部分：

# 意图路由表 | 场景示例 | 路由模块 | 加载文件 | |----------|----------|----------| | "查订单"、"订单状态"、"我的订单" | query | modules/query/query.md | | "物流"、"快递到哪了"、"发货了吗" | logistics | modules/logistics/logistics.md | | "退款"、"退货"、"申请退款" | refund | modules/refund/refund.md | # 全局规则 1. 所有查询默认查询当前登录用户 2. 涉及金额的操作必须二次确认 3. 禁止直接执行 DELETE / UPDATE 等写操作 4. 订单数据以系统实际数据为准，禁止推测

Step 3：编写子模块

以modules/query/query.md为例：

# 订单查询模块 ## 执行流程 1. 确认查询条件（订单号 / 用户ID / 时间范围） 2. 调用 `order_query_api(query_params)` 查询 3. 格式化结果返回给用户 ## 查询模板 ### 按订单号查询 SELECT * FROM orders WHERE order_id = '{order_id}'; ### 按用户ID查询 SELECT * FROM orders WHERE user_id = '{user_id}' ORDER BY created_at DESC LIMIT 20; ### 按时间范围查询 SELECT * FROM orders WHERE user_id = '{user_id}' AND created_at BETWEEN '{start_date}' AND '{end_date}' ORDER BY created_at DESC;

Step 4：打包验证

skill-creator validate order-query

验证项包括：frontmatter 完整性、name/description 是否存在、目录结构合法性。

Step 5：版本管理

cdorder-querygitinitgitadd.gitcommit-m"feat: init order-query skill"

整个流程总结：

AI 对话描述意图 → 初始化目录 → 编写 SKILL.md + 子模块 → 打包验证 → Git 提交

从头到尾不需要手动执行任何命令——你只负责描述意图，AI 负责执行。这也是 Agent Skill 的设计初衷：让 AI 成为真正的协作伙伴。

六、性能对比：有 Skill vs 无 Skill

为直观感受 Skill 对上下文效率的影响，以"查询最近 5 笔订单的物流状态"为测试任务，对比两种配置方式：

测试说明：无 Skill 组使用完整 System Prompt 包含 8 个领域的全部规则（订单、库存、支付、用户、营销、物流、售后、报表）；有 Skill 组仅触发 order-query Skill。Token 消耗和延迟数据为基于典型场景的参考估计值，实际值取决于模型和平台。

有 Skill 的方案在首次响应 token 消耗上仅为无 Skill 方案的约 22%，任务完成率反而从 70% 提升到 95%——更小的上下文意味着更少的噪音，模型聚焦准确度更高。

七、工程化最佳实践

7.1 工具隔离与权限最小化

当 Skill 涉及多个模块时，必须实施模块级工具隔离——每个模块只能调用其白名单中的接口。

# SKILL.md 全局级allowed-tools:[Read,sql:read]# modules/refund/refund.md 中显式声明allowed-tools:[Read,sql:read,sql:update]# 退款模块需更新订单状态

设计原则：

1. 白名单制：每个模块的 tools.md 明确列出可用接口，白名单外一律禁止
2. 危险接口显式禁用：万能工具（如直接 HTTP 调用）全局禁止
3. 工具隔离：不同模块使用不同接口集合，防止误调用

7.2 脚本化确定性计算 —— 突破 LLM 能力边界

凡是 LLM 有概率出错、但脚本能 100% 确定性完成的操作，都应该封装成脚本：

脚本设计四原则：

• 自愈性：内部处理所有异常，始终正常退出，绝不阻断 Skill 主流程
• 结构化输出：统一输出 JSON，方便 Agent 解析和流转
• 幂等性：多次执行结果一致，预检脚本只追加缺失项
• 安全边界：只操作指定文件，不触碰其他系统资源

7.3 参数传递：快照机制

跨阶段的参数传递建议采用快照（Snapshot）机制：

{"currentOrderId":"ORD20260706-001","queryType":"logistics","snapshotVersion":2,"lastUsed":"2026-07-06"}

每个阶段将产出写入快照，下一阶段从快照读取。阶段门卡检查参数完整性，确保参数不丢失、可追溯、可校验。

7.4 测试维度

Skill 的测试不能只跑 Happy Path：

高效迭代的关键：建立日志采集机制，记录每次 Skill 执行的触发匹配、路由分发和执行结果，便于持续优化触发精准度和执行质量。

7.5 适用边界

Skill 并非万能解药，以下场景需要权衡：

• 极小规模项目（3-5 条规则）：直接用 System Prompt 即可，Skill 的目录开销反而多余
• 跨 Agent 互操作：Skill 解决的是"教 Agent 怎么做"，若需要"让 Agent 调用外部服务"，应结合 MCP（Model Context Protocol）
• 实时数据依赖强的场景：Skill 适合封装工作流知识，不适合替代实时数据管道

八、总结

Agent Skill 的核心价值不在于"多了一种配置方式"，而在于它重新定义了 AI Agent 获取知识的方式——从 “被动灌输” 到 “按需激活”。渐进性披露让每个 Skill 在未被触发时几乎零成本，在被激活后精准高效地提供专业指导。

回顾本文核心要点：

1. 渐进性披露是 Skill 的灵魂：Discovery → Activation → Execution 三阶段按需加载。
2. SKILL.md = 路由器：控制在 500 行以内，业务细节下沉到子模块。
3. description 决定触发命中率：枚举触发词、明确排除边界、使用第三人称。
4. 工程化实践：工具隔离、脚本化确定性计算、快照参数传递、系统化测试。

对于正在构建 AI Agent 系统的团队，建议从最小的 Skill 开始——选一个高频场景，按本文流程跑通，感受渐进性披露带来的上下文效率提升，再逐步扩展 Skill 体系。

本文基于阿里云开发者「Harness 工程之道：Skill 原理与最佳实践」的个人理解与实践总结。

参考资源

• Agent Skills 官方规范
• Claude Code 官方文档
• 阿里云百炼平台

感谢阅读，记得点赞、关注、收藏，欢迎各位评论区交流！！！