Skill技能学习思路目标理解 Skill 作为一种给 AI 描述能力的范式掌握不同形态下的设计方法能够根据场景选择合适的 Skill 形态。核心认知Skill 不是某种固定的技术实现而是一种让 AI 知道它能做什么、什么时候做的开发方式。它可以是一个 yaml 文件、一段代码、一个接口、甚至一句话。一、学习地图总览第一层理解本质知道 Skill 是什么、为什么出现、和传统开发方式的区别 第二层掌握三要素会写 任何 Skill 都包含触发条件 能力描述 执行方式 第三层选择形态会用 yaml 形态、代码形态、接口形态、Prompt 形态根据场景选择 第四层设计原则用好 契约设计、粒度控制、错误处理、副作用声明 第五层组合编排用巧 多个 Skill 串成工作流 第六层生产级治理用久 版本、权限、监控二、Skill 的本质2.1 一句话理解Skill 给 AI 写的能力说明书。说明书里写清楚三件事什么时候用触发条件能干什么能力描述怎么干执行方式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:targetdescription:部署目标路径required:false3.3 执行方式How定义Skill 被触发后具体怎么执行。常见执行方式方式说明示例AI 推理执行AI 自己写步骤、调用工具Claude Code SkillAI 读 prompt 后自己决定怎么部署代码执行调用写好的代码逻辑RefundSkill.execute()执行确定性的退款流程接口调用调用远程 API调用天气查询接口、支付接口工作流执行按预设流程执行先 A 再 B 再 C配置好的流程执行方式示例prompt:|### 服务器配置信息示例 - 生产服务器: 192.168.1.100 - 用户名: deploy_user - 端口: 22### 执行前确认1. 确认目标路径:{{args.target}}2. 确认操作环境 3. 获得用户明确授权后再执行tools:-Bash-AskUserQuestionAI 读到这个 prompt知道服务器信息后自己决定怎么执行问用户确认、用 Bash 连接服务器。四、Skill 的形态详解4.1 YAML 形态Claude Code 风格特点定义触发条件 prompt 模板 可用工具AI 自己推理执行。name:deploy-appdescription:|## 触发词 部署到服务器, 远程部署## 能力声明提供服务器部署能力## 负面约束未经用户确认不执行命令args:-name:targetdescription:部署目标路径required:falseprompt:|用户请求部署到服务器...tools:-Bash-AskUserQuestion适用场景需要 AI 自主决策判断用户意图、选择执行方式流程不固定需要灵活处理开发助手类场景优点灵活、易修改、不需要写代码缺点执行不确定AI 每次可能做法不同、难测试、难监控4.2 代码形态特点用代码封装确定的业务逻辑AI 只负责决定调不调用不负责怎么执行。classProcessRefundSkill:defexecute(self,input_data:dict)-dict:# 1. 查订单orderself.order_repo.get(input_data[order_id])ifnotorder:return{success:False,fail_reason:订单不存在}# 2. 校验条件iforder.days_since_delivery()7:return{success:False,fail_reason:已超过退款期限}# 3. 创建退款单refundself.order_repo.create_refund(...)# 4. 发起退款payment_resultself.payment.refund(...)return{success:True,refund_id:refund.id}适用场景需要确定性的业务逻辑退款、支付、库存扣减涉及资金、安全、合规需要精确的错误处理和回滚优点执行确定、可测试、可监控、性能高缺点开发成本高、修改需要重新部署4.3 接口形态特点Skill 本身就是个远程服务通过 HTTP 调用。name:query_weatherendpoint:GET https://api.weather.com/v1/currentinput_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 CodeYAML灵活AI 自主决策支付/退款/库存代码确定性高可回滚调用第三方 API接口复用现有服务内部工具/原型Prompt快速验证需要版本管理的企业级应用YAML 代码混合触发用 YAML执行用代码五、Skill 的设计原则5.1 契约设计输入输出任何 Skill 都要明确给什么、返回什么。❌ 差的契约 输入随便给 输出看着办 ✅ 好的契约 输入 订单号: string, 必填, 格式 ORD-YYYYMMDD-XXXX 退款原因: string, 必填, 枚举[质量问题, 不想要了, 发错货] 输出 成功: boolean 退款单号: string, 成功时返回 失败原因: string, 失败时返回5.2 粒度控制粒度过细一个简单业务调 8 个 SkillAI 决策负担重。粒度过粗一个 Skill 500 行代码内部逻辑复杂。判断标准一个 Skill 对应一个用户能听懂的业务动作执行时间 5 秒输入参数 10 个可以被多个场景复用5.3 错误处理Skill 的错误信息要分层错误类型用户看到开发者看到参数错误“请检查输入信息”订单号格式错误expected ORD-YYYYMMDD-XXXX业务规则“该订单已超过退款期限”BUSINESS_RULE: delivery_age15, max7系统异常“系统繁忙请稍后重试”DB_CONNECTION_TIMEOUT: retry_count25.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新增功能新增可选参数修订号 1Bug 修复7.2 权限控制permissions:callers:# 谁可以调用-after_sales_system-admin_portaldata_scope:# 数据范围region:[华东,华南]environments:# 环境限制-production-testing7.3 监控指标说明调用次数每秒/每分钟调用量成功率成功调用 / 总调用延迟P50/P90/P99 响应时间错误分布按错误类型分类八、常见陷阱陷阱 1把业务逻辑全写在 prompt 里现象YAML Skill 的 prompt 里写了 50 行业务规则AI 执行时经常漏步骤。解决复杂业务逻辑用代码封装YAML 只写触发条件和调用说明。陷阱 2Skill 粒度过细现象一个简单业务调 8 个 SkillAI 决策负担重。解决检查这些 Skill 是否总是一起调用如果是合并成一个。陷阱 3契约变更不兼容现象Skill 升级后下游调用方报错。解决保持向后兼容不兼容变更走主版本升级。陷阱 4副作用未声明现象AI 调用 Skill 后发现数据被改了、短信被发了。解决注册时必须声明副作用列表重要操作需要二次确认。陷阱 5错误信息太技术现象返回ERROR_CODE_5003: DB_CONNECTION_TIMEOUT用户看不懂。解决错误信息分层用户看业务提示开发者看技术日志。九、实战场景场景 1电商售后用户说我要退款 ↓ AI 识别意图 → 触发处理退款Skill ↓ 处理退款Skill代码形态执行 1. 查订单 → 2. 校验条件 → 3. 创建退款单 → 4. 发起退款 → 5. 通知用户 ↓ 返回结果给 AI → AI 组织语言回复用户形态选择触发用 YAMLAI 识别意图执行用代码退款流程确定性高。场景 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