Skills 多步骤流程设计
简单任务只需一个步骤，但现实中的工作流往往涉及多个环节。
本篇介绍如何将复杂任务拆解为清晰的步骤，并在 SKILL.md 中组织成可靠的执行流程。
为什么要显式定义步骤
Claude 很聪明，但在没有明确步骤指导的情况下，它可能会跳过某些环节，或者以不一致的顺序执行。
显式步骤的好处：
一是让 Claude 的行为可预测；二是便于用户理解正在发生什么；三是出错后容易定位到哪一步出了问题。
步骤设计的基本原则
| 原则 | 说明 |
|---|---|
| 每步只做一件事 | 避免一个步骤同时完成多个不相关的操作 |
| 步骤间有明确的输入输出 | 上一步的输出是下一步的输入，不依赖隐式状态 |
| 每步执行后给出反馈 | 告知用户该步骤完成了什么，以及下一步是什么 |
| 允许中途中断 | 用户可以在任意步骤暂停或修改参数 |
在 SKILL.md 中定义多步骤流程
实例
bash
---
name: excel-report-generator
description: >
根据用户上传的原始数据，生成格式化的 Excel 报告，包含数据清洗、
图表生成、摘要统计三个环节。当用户需要数据报告、Excel 输出、
自动化统计时触发。
---
# Excel 报告生成器
## 执行流程
### 第一步：读取并验证数据
1. 检查文件是否存在，格式是否为 .csv 或 .xlsx
2. 读取文件，输出基本信息：
- 总行数、总列数
- 各列的数据类型
- 空值数量统计
3. 若发现严重问题（如文件为空、格式不支持），停止并告知用户
**输出**：数据基本信息报告（在对话中展示）
---
### 第二步：数据清洗
运行 `scripts/clean_data.py`，执行：
- 删除完全重复的行
- 将数值列中的空值填充为 0
- 去除字符串首尾空格
输出清洗后的数据到 `/home/claude/cleaned_data.csv`
**输出**：清洗报告（删除了多少行、修改了多少值）
---
### 第三步：生成统计摘要
运行 `scripts/calc_stats.py`，计算：
- 各数值列的均值、中位数、标准差
- 按时间列分组的趋势数据（若存在时间列）
输出到 `/home/claude/stats.json`
---
### 第四步：生成 Excel 报告
运行 `scripts/gen_excel.py`，生成包含以下内容的 Excel 文件：
- Sheet1：清洗后的原始数据
- Sheet2：统计摘要表格
- Sheet3：折线图（若存在时间序列数据）
将最终文件保存到 `/mnt/user-data/outputs/report_YYYYMMDD.xlsx`
**输出**：调用 present_files 展示文件，提供下载链接
---
### 错误处理
任意步骤失败时：
1. 展示完整错误信息
2. 说明可能的原因
3. 询问用户是否想要跳过当前步骤或修改参数后重试步骤脚本的组织方式
多步骤流程的每个步骤可以对应一个独立的脚本文件，也可以合并为一个主脚本。
方案一：每步一个脚本（推荐用于复杂流程）
bash
excel-report-generator/
├── SKILL.md
└── scripts/
├── clean_data.py # 第二步：数据清洗
├── calc_stats.py # 第三步：统计计算
└── gen_excel.py # 第四步：生成报告方案二：单一主脚本（适合简单流程）
实例
python
# 文件路径：scripts/pipeline.py
# 单一主脚本，通过 --step 参数控制执行哪一步
import argparse
import sys
def step_clean(input_file: str, output_file: str) -> dict:
"""第二步：数据清洗"""
print(f"正在清洗数据：{input_file}")
# 实际清洗逻辑...
return {"status": "success", "removed_rows": 3, "fixed_values": 12}
def step_stats(input_file: str, output_file: str) -> dict:
"""第三步：统计计算"""
print(f"正在计算统计数据：{input_file}")
# 实际统计逻辑...
return {"status": "success", "columns_analyzed": 5}
def step_excel(data_file: str, stats_file: str, output_file: str) -> dict:
"""第四步：生成 Excel"""
print(f"正在生成 Excel 报告：{output_file}")
# 实际生成逻辑...
return {"status": "success", "output": output_file}
STEPS = {
"clean": step_clean,
"stats": step_stats,
"excel": step_excel,
}
if __name__ == "__main__":
parser = argparse.ArgumentParser()
parser.add_argument("--step", required=True, choices=STEPS.keys(),
help="要执行的步骤：clean / stats / excel")
parser.add_argument("--input", required=True, help="输入文件路径")
parser.add_argument("--output", required=True, help="输出文件路径")
args = parser.parse_args()
import json
result = STEPS[args.step](args.input, args.output)
print(json.dumps(result, ensure_ascii=False, indent=2))在 SKILL.md 中调用该脚本：
实例
bash
# 第二步：数据清洗
python scripts/pipeline.py \
--step clean \
--input /mnt/user-data/uploads/runoob_sales.csv \
--output /home/claude/cleaned_data.csv
# 第三步：统计计算
python scripts/pipeline.py \
--step stats \
--input /home/claude/cleaned_data.csv \
--output /home/claude/stats.json步骤间的依赖检查
后续步骤依赖前面步骤的输出文件时，执行前应先检查依赖文件是否存在。
实例
bash
# 文件路径：scripts/check_deps.py
import os
import sys
def check_step_deps(step_name: str, required_files: list) -> bool:
"""
检查某步骤的前置文件是否已生成
参数：
step_name: 当前步骤名称（用于错误提示）
required_files: 需要存在的文件路径列表
返回：
True 表示所有依赖就绪，False 表示有文件缺失
"""
missing = [f for f in required_files if not os.path.exists(f)]
if missing:
print(f"错误：{step_name} 缺少前置文件：")
for f in missing:
print(f" - {f}")
print("请先完成前置步骤。")
return False
return True
# 使用示例：在第四步生成 Excel 前检查前置文件
if __name__ == "__main__":
deps = [
"/home/claude/cleaned_data.csv",
"/home/claude/stats.json"
]
if not check_step_deps("生成 Excel 报告", deps):
sys.exit(1)
print("所有前置文件就绪，开始生成报告...")bash
错误：生成 Excel 报告 缺少前置文件：
- /home/claude/stats.json
请先完成前置步骤。复杂流程中，步骤间的依赖关系容易被忽视。明确的依赖检查可以在错误发生时立刻定位到缺失的环节，而不是在最后一步才暴露问题。
AI 思考中...