Skill（技能）学习思路

目标：理解 Skill 作为一种"给 AI 描述能力"的范式，掌握不同形态下的设计方法，能够根据场景选择合适的 Skill 形态。

核心认知：Skill 不是某种固定的技术实现，而是一种"让 AI 知道它能做什么、什么时候做"的开发方式。它可以是一个 yaml 文件、一段代码、一个接口、甚至一句话。

---

一、学习地图（总览）

第一层：理解本质（知道）
    Skill 是什么、为什么出现、和传统开发方式的区别

第二层：掌握三要素（会写）
    任何 Skill 都包含：触发条件 + 能力描述 + 执行方式

第三层：选择形态（会用）
    yaml 形态、代码形态、接口形态、Prompt 形态，根据场景选择

第四层：设计原则（用好）
    契约设计、粒度控制、错误处理、副作用声明

第五层：组合编排（用巧）
    多个 Skill 串成工作流

第六层：生产级治理（用久）
    版本、权限、监控

---

二、Skill 的本质

2.1 一句话理解

Skill = 给 AI 写的能力说明书。

说明书里写清楚三件事：

1. 什么时候用（触发条件）
2. 能干什么（能力描述）
3. 怎么干（执行方式）

2.2 为什么 Skill 是一种"范式"

以前的开发方式：

程序员写代码 → 代码控制所有逻辑 → 用户按固定流程操作

Skill 范式：

程序员写能力说明书 → AI 自己决定什么时候用什么能力 → 用户用自然语言交互

区别：以前是人告诉机器"第一步做什么、第二步做什么"；现在是机器自己看说明书，决定"用户需要我做什么"。

2.3 Skill 的多种形态

不要纠结格式。Skill 可以长这样：

形态	例子	适用场景
YAML 文件	Claude Code 的 skill.yaml	定义触发条件、prompt 模板、可用工具
代码类/函数	class RefundSkill	封装确定的业务逻辑
HTTP 接口	POST /api/refund	调用远程服务
Prompt 里的一句话	“你可以查天气”	简单能力声明
JSON 配置	{"name": "查询订单", "endpoint": "..."}	注册到能力中心

核心不是形态，而是三要素。只要包含"什么时候用、能干什么、怎么干"，就是 Skill。

---

三、Skill 的三要素

任何 Skill，不管长什么样，都包含这三个部分：

3.1 触发条件（When）

定义：什么情况下，这个 Skill 应该被激活。

常见触发方式：

方式	说明	示例
关键词触发	用户话里出现特定词	“部署”、“退款”、“查订单”
意图识别	AI 判断用户意图匹配	用户说"我不想买了"→意图是"退款"
主动触发	AI 自己决定该用	检测到异常日志，主动调用告警 Skill
定时触发	到点就执行	每天凌晨调用"生成日报"Skill

触发条件示例：

description: |
  ## 触发词
  "部署到服务器", "deploy to server", "远程部署"

3.2 能力描述（What）

定义：这个 Skill 具体能做什么、需要什么、返回什么。

能力描述通常包含：

- 名称和简介：这个 Skill 是干嘛的
- 输入参数：需要什么数据
- 输出结果：返回什么数据
- 约束条件：什么情况下不能用
- 副作用：执行后会改数据吗？会发通知吗？

能力描述示例：

description: |
  ## 能力声明
  提供服务器部署能力
  
  ## 负面约束
  未经用户确认不执行命令
  
  ## 边界排除
  不处理本地部署

args:
  - name: target
    description: 部署目标路径
    required: false

3.3 执行方式（How）

定义：Skill 被触发后，具体怎么执行。

常见执行方式：

方式	说明	示例
AI 推理执行	AI 自己写步骤、调用工具	Claude Code Skill，AI 读 prompt 后自己决定怎么部署
代码执行	调用写好的代码逻辑	RefundSkill.execute() 执行确定性的退款流程
接口调用	调用远程 API	调用天气查询接口、支付接口
工作流执行	按预设流程执行	先 A 再 B 再 C，配置好的流程

执行方式示例：

prompt: |
  ### 服务器配置信息（示例）
  - 生产服务器: 192.168.1.100
  - 用户名: deploy_user
  - 端口: 22
  
  ### 执行前确认
  1. 确认目标路径: {{args.target}}
  2. 确认操作环境
  3. 获得用户明确授权后再执行

tools:
  - Bash
  - AskUserQuestion

AI 读到这个 prompt，知道服务器信息后，自己决定怎么执行（问用户确认、用 Bash 连接服务器）。

---

四、Skill 的形态详解

4.1 YAML 形态（Claude Code 风格）

特点：定义触发条件 + prompt 模板 + 可用工具，AI 自己推理执行。

name: deploy-app
description: |
  ## 触发词
  "部署到服务器", "远程部署"
  
  ## 能力声明
  提供服务器部署能力
  
  ## 负面约束
  未经用户确认不执行命令

args:
  - name: target
    description: 部署目标路径
    required: false

prompt: |
  用户请求部署到服务器...
  
tools:
  - Bash
  - AskUserQuestion

适用场景：

• 需要 AI 自主决策（判断用户意图、选择执行方式）
• 流程不固定，需要灵活处理
• 开发助手类场景

优点：灵活、易修改、不需要写代码
缺点：执行不确定（AI 每次可能做法不同）、难测试、难监控

---

4.2 代码形态

特点：用代码封装确定的业务逻辑，AI 只负责决定"调不调用"，不负责"怎么执行"。

class ProcessRefundSkill:
    def execute(self, input_data: dict) -> dict:
        # 1. 查订单
        order = self.order_repo.get(input_data["order_id"])
        if not order:
            return {"success": False, "fail_reason": "订单不存在"}
        
        # 2. 校验条件
        if order.days_since_delivery() > 7:
            return {"success": False, "fail_reason": "已超过退款期限"}
        
        # 3. 创建退款单
        refund = self.order_repo.create_refund(...)
        
        # 4. 发起退款
        payment_result = self.payment.refund(...)
        
        return {"success": True, "refund_id": refund.id}

适用场景：

• 需要确定性的业务逻辑（退款、支付、库存扣减）
• 涉及资金、安全、合规
• 需要精确的错误处理和回滚

优点：执行确定、可测试、可监控、性能高
缺点：开发成本高、修改需要重新部署

---

4.3 接口形态

特点：Skill 本身就是个远程服务，通过 HTTP 调用。

name: query_weather
endpoint: GET https://api.weather.com/v1/current
input_schema:
  city: {type: string, required: true}
output_schema:
  temperature: {type: number}
  condition: {type: string}

适用场景：

• 调用第三方服务（天气、地图、翻译）
• 企业内部已有微服务
• 需要跨系统复用

优点：复用现有服务、语言无关
缺点：网络依赖、需要处理超时和降级

---

4.4 Prompt 形态

特点：在系统提示里用一句话声明能力，最简单。

你是一位智能助手，你可以：
1. 查询天气（告诉我城市名）
2. 查询订单（告诉我订单号）
3. 处理退款（告诉我订单号和原因）

适用场景：

• 极简场景，只有一两个能力
• MVP 验证阶段
• 内部原型

优点：最简单，零成本
缺点：没有结构化约束，容易出错

---

4.5 形态选择指南

场景	推荐形态	理由
AI 开发助手（Claude Code）	YAML	灵活，AI 自主决策
支付/退款/库存	代码	确定性高，可回滚
调用第三方 API	接口	复用现有服务
内部工具/原型	Prompt	快速验证
需要版本管理的企业级应用	YAML + 代码混合	触发用 YAML，执行用代码

---

五、Skill 的设计原则

5.1 契约设计（输入输出）

任何 Skill 都要明确：给什么、返回什么。

❌ 差的契约：
输入：随便给
输出：看着办

✅ 好的契约：
输入：
  订单号: string, 必填, 格式 ORD-YYYYMMDD-XXXX
  退款原因: string, 必填, 枚举：[质量问题, 不想要了, 发错货]

输出：
  成功: boolean
  退款单号: string, 成功时返回
  失败原因: string, 失败时返回

5.2 粒度控制

粒度过细：一个简单业务调 8 个 Skill，AI 决策负担重。
粒度过粗：一个 Skill 500 行代码，内部逻辑复杂。

判断标准：

• 一个 Skill 对应一个"用户能听懂"的业务动作
• 执行时间 < 5 秒
• 输入参数 < 10 个
• 可以被多个场景复用

5.3 错误处理

Skill 的错误信息要分层：

错误类型	用户看到	开发者看到
参数错误	“请检查输入信息”	订单号格式错误：expected ORD-YYYYMMDD-XXXX
业务规则	“该订单已超过退款期限”	BUSINESS_RULE: delivery_age=15, max=7
系统异常	“系统繁忙，请稍后重试”	DB_CONNECTION_TIMEOUT: retry_count=2

5.4 副作用声明

必须声明：执行这个 Skill 会改数据吗？会发通知吗？会扣款吗？

side_effects:
  - 修改订单状态
  - 创建退款记录
  - 调用支付网关（扣款）
  - 发送短信通知

AI 调用前可以检查：“这个操作会扣款，需要用户二次确认吗？”

---

六、Skill 的组合编排

多个 Skill 可以组合成复杂流程。

6.1 串行

Skill A → Skill B → Skill C

前一个的输出作为后一个的输入。

例子：创建订单 → 发起支付 → 确认支付

6.2 并行

      ┌→ 查询库存
输入 ──┼→ 查询价格
      └→ 查询优惠券

多个 Skill 同时执行，互不影响。

例子：同时查库存、价格、优惠券，汇总后展示给用户。

6.3 条件分支

输入 → 判断用户等级
         ├── VIP → 快速退款
         ├── 普通 → 标准退款
         └── 企业 → 对公退款

例子：根据用户类型选择不同的处理流程。

---

七、生产级治理

7.1 版本管理

Skill 修改会影响线上效果，需要版本管理。

skills/
├── process_refund/
│   ├── v1.0.0/
│   ├── v1.1.0/
│   ├── v2.0.0/
│   └── latest -> v1.1.0/

版本号含义：

• 主版本 +1：不兼容的契约变更（删必填参数）
• 次版本 +1：新增功能（新增可选参数）
• 修订号 +1：Bug 修复

7.2 权限控制

permissions:
  callers:          # 谁可以调用
    - after_sales_system
    - admin_portal
  data_scope:       # 数据范围
    region: [华东, 华南]
  environments:     # 环境限制
    - production
    - testing

7.3 监控

指标	说明
调用次数	每秒/每分钟调用量
成功率	成功调用 / 总调用
延迟	P50/P90/P99 响应时间
错误分布	按错误类型分类

---

八、常见陷阱

陷阱 1：把业务逻辑全写在 prompt 里

现象：YAML Skill 的 prompt 里写了 50 行业务规则，AI 执行时经常漏步骤。

解决：复杂业务逻辑用代码封装，YAML 只写触发条件和调用说明。

陷阱 2：Skill 粒度过细

现象：一个简单业务调 8 个 Skill，AI 决策负担重。

解决：检查这些 Skill 是否总是一起调用，如果是，合并成一个。

陷阱 3：契约变更不兼容

现象：Skill 升级后，下游调用方报错。

解决：保持向后兼容，不兼容变更走主版本升级。

陷阱 4：副作用未声明

现象：AI 调用 Skill 后发现数据被改了、短信被发了。

解决：注册时必须声明副作用列表，重要操作需要二次确认。

陷阱 5：错误信息太技术

现象：返回 ERROR_CODE_5003: DB_CONNECTION_TIMEOUT，用户看不懂。

解决：错误信息分层，用户看业务提示，开发者看技术日志。

---

九、实战场景

场景 1：电商售后

用户说"我要退款"
    ↓
AI 识别意图 → 触发"处理退款"Skill
    ↓
"处理退款"Skill（代码形态）执行：
    1. 查订单 → 2. 校验条件 → 3. 创建退款单 → 4. 发起退款 → 5. 通知用户
    ↓
返回结果给 AI → AI 组织语言回复用户

形态选择：触发用 YAML（AI 识别意图），执行用代码（退款流程确定性高）。

场景 2：智能客服

用户提问
    ↓
AI 判断意图（查订单/退款/改地址/投诉）
    ↓
调用对应 Skill
    ↓
返回结果 → AI 生成回复

形态选择：意图识别用 YAML 配置，各 Skill 根据复杂度选择代码或接口。

场景 3：数据报表

用户说"生成上周销售报表"
    ↓
AI 触发"生成报表"Skill
    ↓
并行调用：
    ├→ 查询销售数据
    ├→ 查询用户数据
    └→ 查询商品数据
    ↓
汇总 → 生成图表 → 生成 PDF
    ↓
返回下载链接

形态选择：编排用 YAML/配置，数据查询用接口，PDF 生成用代码。

---

十、与知识图谱的对应关系

知识图谱条目	本章对应章节	说明
Skill 抽象定义	二、Skill 的本质	范式定义 + 多种形态
Skill 输入输出契约	五、设计原则 5.1	契约设计
Skill 注册与发现机制	三、3.1 触发条件	什么时候激活
Skill 组合编排	六、组合编排	串行/并行/条件
Skill 与 Tool/Function 的层级关系	四、形态详解	不同形态的对比
Skill 热更新与版本控制	七、生产级治理 7.1	版本管理
Skill 权限与作用域	七、生产级治理 7.2	权限控制
Skill 市场/生态	四、4.5 形态选择	根据场景选择形态

---

最后更新：2026-05-12