快速掌握Skill：大模型时代的可复用能力单元

核心痛点	详细说明
重复造轮子	相同的业务逻辑、工具调用逻辑，在不同项目、不同场景中反复开发实现，效率极低
执行能力受限	纯 Prompt 仅能实现文本交互，无法直接调用外部工具，不能读写文件、请求API、操作数据库
维护成本极高	任务逻辑散落于各类对话、脚本、代码中，统一修改、迭代升级需要多处同步，极易出错

Skill 带来的核心变革：一次编写、多处复用；打通大模型与外部系统的交互能力；统一标准化格式，支持快速共享、迭代和维护。

三、Skill vs Workflow：核心区别

核心定位差异：Skill 定义「怎么做一件事」（原子能力单元），Workflow 定义「先做A再做B」（业务流程编排）。

对比维度	Skill（技能单元）	Workflow（工作流）
能力粒度	功能级原子能力（如：生成周报、解析CSV、调用接口）	业务级流程组合（如：拉取数据→生成周报→推送邮件）
调用方式	被 Agent、其他 Skill、Workflow 调用	独立执行、定时触发、手动触发
执行灵活性	支持内部条件分支、逻辑判断，适配复杂单任务	执行路径相对固定，侧重流程顺序编排
形象类比	乐高积木（基础可复用单元）	搭建说明书（积木组合流程）

二者关联关系：Workflow 是多个 Skill 的组合编排，依靠原子 Skill 实现具体任务执行，Skill 是 Workflow 的最小能力底座。

四、如何使用Skill？

4.1 Skill 完整结构示例

标准 Skill 文件由「YAML元数据区」+「Markdown指令执行区」两部分组成，结构规范、开箱即用：

开始
↓
┌─────────────────────────────────────────────┐
│ 【元数据区域】（标准YAML格式，用于引擎识别与校验） │
└─────────────────────────────────────────────┘
↓
1. 解析元数据
→ 读取 name/version/requires 等核心字段
→ 校验 YAML 格式合法性，过滤无效 Skill
↓
┌─────────────────────────────────────────────┐
│ 【指令执行区域】（Markdown+代码块，核心执行逻辑） │
└─────────────────────────────────────────────┘
↓
2. 检查依赖环境
→ 校验基础运行环境（如 Python3）
→ 批量检查 requires 中声明的依赖库/工具
→ 依赖缺失 → 终止执行并提示用户补全环境
↓
3. 准备执行上下文
→ 初始化独立工作目录（临时/指定目录）
→ 开启全局变量传递机制，支持步骤间数据共享
↓
【步骤1】读取 CSV 文件
→ 按 Markdown 顺序执行代码块
↓
【步骤2】计算销售额汇总
→ 基于业务字段 amount，完成销售额统计计算 # 注释
↓
【步骤3】保存结果到文件（可选）
→ 结构化输出结果，为后续 Skill/Workflow 提供数据依赖
→ 写入本地 JSON 文件，实现数据持久化 # 注释
↓
【步骤4】返回执行状态
→ 统一结束输出，标识任务执行完成 # 注释
↓
4. 顺序执行代码指令（总体说明）
→ 所有代码块共享同一个解释器进程，变量全局互通
→ 支持单步骤异常拦截、日志输出
↓
5. 全局错误处理
→ 任意代码块抛出异常 → 立即终止全流程
→ 精准返回错误类型、行号、堆栈信息，便于排查
↓
6. 返回最终执行结果
→ 执行成功：输出全部日志 + 生成文件路径
→ 执行失败：返回标准化错误描述，无脏数据输出
↓
结束

4.2 Skill 完整执行流程（引擎底层逻辑）

开始 ↓ ┌─────────────────────────────────────────────┐ │ 【元数据区域】 │ │ 解析YAML格式，校验核心字段，过滤无效Skill │ └─────────────────────────────────────────────┘ ↓ 1. 解析元数据 → 读取 name/version/requires 等核心字段 → 校验 YAML 格式合法性，过滤无效 Skill ↓ ┌─────────────────────────────────────────────┐ │ 【指令执行区域】 │ │ 顺序执行代码块，共享解释器进程 │ └─────────────────────────────────────────────┘ ↓ 2. 检查依赖环境 → 校验基础运行环境（如 Python3） → 批量检查 requires 中声明的依赖库/工具 → 依赖缺失 → 终止执行并提示用户补全环境 ↓ 3. 准备执行上下文 → 初始化独立工作目录（临时/指定目录） → 开启全局变量传递机制，支持步骤间数据共享 ↓ 4. 顺序执行代码指令 → 按 Markdown 文档顺序逐块执行代码 → 所有代码块共享同一个解释器进程，变量全局互通 → 支持单步骤异常拦截、日志输出 ↓ 5. 全局错误处理 → 任意代码块抛出异常 → 立即终止全流程 → 精准返回错误类型、行号、堆栈信息，便于排查 ↓ 6. 返回最终执行结果 → 执行成功：输出全部日志 + 生成文件路径 → 执行失败：返回标准化错误描述，无脏数据输出 ↓ 结束

4.3 Skill 编写最佳实践（附原理注释）

最佳实践	详细说明 & 设计原因
标准化命名	采用业务语义命名（如`customer_segmentation.md`），禁止 `task1.md` 等无意义命名；便于团队检索、复用、统一管理
全流程注释	代码块前用标题标注步骤目标，代码内部添加关键逻辑注释；降低维护成本，方便他人迭代、调试、二次开发
参数化输入	使用 `${input_file}` 占位符动态传参，杜绝文件路径、参数硬编码；大幅提升Skill通用性，适配多场景复用
先测试后上线	使用 test 目录小样本数据完成功能验证，再投入生产环境；避免大文件、真实业务数据出错，防止问题扩散
模块化拆分	单Skill代码超50行需拆分，拆解为数据加载、计算、输出等原子子Skill；逻辑解耦，更灵活、易复用、易维护