顺序步骤与条件分支设计
一个 Skill 的执行路径很少是完全线性的。真实的工作流中，总会遇到"如果测试失败就停止"、"如果文件不存在就用默认值"、"如果是 production 环境就增加额外确认"这样的分支逻辑。
顺序步骤的基本结构
清晰的顺序步骤让 Claude 按照确定性的顺序执行，减少歧义：
## 执行步骤
1. [前置验证] 验证参数和资源可用性
2. [数据收集] 调用工具收集所需信息
3. [分析处理] 对收集到的信息进行分析
4. [结果输出] 生成格式化的报告
关键原则：每个步骤应该有明确的输入和输出。步骤之间的数据流应该清晰。
条件分支的表达方式
在 Skill 文件中，用自然语言描述条件分支：
方式一：直接的 if/else 描述
## 执行步骤
3. 运行 `npm test` 获取测试结果：
- **如果测试全部通过**（退出码 0）：继续步骤 4
- **如果有测试失败**（退出码非 0）：
- 列出失败的测试用例
- 停止执行并输出失败报告
- 不继续步骤 4
4. 执行部署前的最终检查...
方式二：子步骤条件
3. 确定分析范围：
3a. 如果提供了 `--file` 参数：只分析指定文件
3b. 如果提供了 `--dir` 参数：分析指定目录下的所有文件
3c. 如果两者都未提供：分析当前 Git 仓库中最近修改的文件（`git diff --name-only HEAD~1 HEAD`）
方式三：基于环境的分支
4. 根据 `--env` 参数决定操作：
**staging 环境**：
- 直接继续，不需要额外确认
- 记录日志到 `.claude/logs/check-$(date +%Y%m%d).log`（如果目录存在）
**production 环境**：
- 输出所有检查结果摘要
- 输出最终确认提示："以上是生产环境检查结果，请仔细确认后继续"
- 等待用户确认后再输出最终结论
早期终止模式
在工作流中，有时应该在中途停止而不是继续到最后。明确描述终止条件：
## 执行步骤
### 阶段一：前置检查（任何失败都终止）
1. 验证 `--env` 参数有效性
- ❌ 如果无效：终止，输出用法说明
2. 检查 Git 工作区状态
- 运行 `git status --porcelain`
- ❌ 如果有未提交的修改：
```
❌ 部署检查中止：发现未提交的修改
以下文件有未提交的更改：
[列出修改的文件]
请先提交或 stash 这些修改，然后重新运行检查。
```
3. 确认目标分支存在
- 运行 `git branch -r | grep {branch}`
- ❌ 如果分支不存在：终止，提示分支名错误
### 阶段二：主要检查（失败记录但不终止）
4. 运行单元测试
- ⚠️ 如果测试失败：记录为"警告"，继续其他检查
5. 检查环境变量配置
- ⚠️ 如果有变量缺失：记录为"警告"，继续
6. 扫描安全漏洞
- ⚠️ 如果有 medium/low 级别漏洞：记录为"警告"，继续
- ❌ 如果有 critical 级别漏洞：终止，输出严重告警
### 阶段三：汇总报告
7. 汇总所有检查结果，生成最终报告
完整示例：环境感知的 pre-deploy Skill
graph TD
A["开始 /pre-deploy"] --> B["验证 --env 参数"]
B --> |无效| STOP1["❌ 终止：参数错误"]
B --> |staging| C1["检查工作区清洁"]
B --> |production| C2["增强检查 + 需确认"]
C1 --> D["运行测试"]
C2 --> D
D --> |"全部通过"| E["检查配置完整性"]
D --> |"有失败"| F{"是 production?"}
F --> |是| STOP2["❌ 终止：测试失败"]
F --> |否| E_warn["继续但标记警告"]
E_warn --> E
E --> G["生成报告"]
G --> H{"有严重问题?"}
H --> |有| STOP3["❌ 阻断：不建议部署"]
H --> |无| OK["✅ 可以部署"]
style STOP1 fill:#ffebee,stroke:#c62828
style STOP2 fill:#ffebee,stroke:#c62828
style STOP3 fill:#ffebee,stroke:#c62828
style OK fill:#e8f5e9,stroke:#2e7d32
对应的 Skill 文件：
---
description: 部署前自动化检查清单，支持 staging 和 production 环境
allowed-tools: Bash, Read, Glob
---
# 部署前检查
## 目标
在部署前自动执行检查清单，确保代码、配置和依赖处于安全可部署状态。
根据目标环境（staging/production）采用不同的严格程度。
## 参数说明（来自 $ARGUMENTS）
- `--env`（必填）：`staging` 或 `production`
- `--skip-tests`（可选）：跳过测试检查（仅 staging 允许）
## 执行步骤
### 阶段一：参数验证（失败则立即终止）
1. 验证 `--env`：必须是 `staging` 或 `production`，否则终止。
2. 如果 `--env` 为 `production` 且提供了 `--skip-tests`：
终止并输出：
```
❌ 错误：production 环境不允许跳过测试检查
请移除 --skip-tests 参数后重试。
```
### 阶段二：工作区检查
3. 运行 `git status --porcelain`：
- **如果有未暂存的修改**：
- staging：记录警告，继续
- production：终止，要求先提交所有修改
4. 运行 `git log --oneline -1` 获取当前 HEAD 提交信息（用于报告）。
### 阶段三：测试检查
5. 如果未提供 `--skip-tests`：
- 运行 `npm test -- --passWithNoTests 2>&1 | tail -30`
- 如果测试失败：
- staging：记录为警告，继续
- production：终止，输出失败的测试用例
6. 如果提供了 `--skip-tests`（仅 staging）：
- 在报告中标记"⏭️ 测试检查已跳过（--skip-tests）"
### 阶段四：配置检查
7. 使用 Glob 找到 `.env.example` 文件（如果存在）
8. 使用 Read 读取 `.env.example` 的内容，提取所有变量名
9. 尝试读取 `.env` 或 `.env.{env}` 文件，检查所有变量是否都已定义
- 缺失的变量：记录为警告
- 注意：不要输出实际的变量值（安全）
### 阶段五：生成报告
10. 汇总所有检查结果，生成格式化报告（见输出格式）
## 输出格式
部署前检查报告
环境：{env} 检查时间：[时间] 当前提交：[commit hash] [commit message]
检查结果
| 检查项 | 状态 | 说明 |
|---|---|---|
| 工作区干净 | ✅/⚠️/❌ | [详情] |
| 单元测试 | ✅/⚠️/⏭️/❌ | [通过N/失败N] |
| 环境配置 | ✅/⚠️ | [缺失变量列表] |
总体结论
[✅ 所有检查通过，可以部署到 {env}] 或 [⚠️ 发现 N 个警告，建议修复后再部署（当前可继续）] 或 [❌ 发现严重问题，不建议部署：[问题摘要]]
本节记录清单
- [ ] 识别你的 Skill 中存在的条件分支点
- [ ] 明确哪些条件导致"终止"，哪些导致"警告后继续"
- [ ] 为 production/staging 等不同场景设计不同的执行路径
- [ ] 用 Mermaid 流程图（在文档中）可视化你的 Skill 执行逻辑
下一节：调用外部 API 与工具失败处理——如何在 Skill 中安全地调用外部 API？工具调用失败时如何优雅地处理？