必填与可选参数、默认值设计

一个设计良好的 Skill，不需要用户记住所有参数——常见场景下用默认值，特殊场景下才显式传参。这一节讲如何在 Skill 文件中描述参数的必填性、默认值和验证逻辑。

必填参数的处理

当 Skill 依赖某个参数才能正确执行时，应在步骤描述中明确处理参数缺失的情况：

## 执行步骤
1. 从 $ARGUMENTS 中解析目标文件路径（第一个位置参数）。
如果没有提供任何参数，立即停止并输出：
```
❌ 错误：此 Skill 需要文件路径参数
用法：/analyze-file <文件路径> [--focus security|performance|style]
示例：/analyze-file src/api/auth.ts --focus security
```
2. 检查文件路径是否存在（使用 Read 工具尝试读取）。
如果文件不存在，停止并输出：
```
❌ 错误：文件 '{路径}' 不存在
请检查路径是否正确。
```
3. （继续正常执行...）

关键设计点：失败时给出明确的用法说明，而不是让 Claude 猜测或继续执行。

可选参数的默认值模式

模式一：在参数说明中声明默认值

## 参数说明（来自 $ARGUMENTS）
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--env` | `staging` | 目标环境（staging / production） |
| `--branch` | 当前 Git 分支 | 要检查的分支名 |
| `--since` | `24h` | 分析时间范围（1h / 24h / 7d / 30d） |
| `--format` | `markdown` | 输出格式（markdown / json / text） |

模式二：在步骤中显式处理默认值

## 执行步骤
1. 解析参数：
- `--env`：如果未提供，使用 `staging`
- `--branch`：如果未提供，运行 `git branch --show-current` 获取当前分支
- `--since`：如果未提供，使用 `24h`（表示过去 24 小时）
- `--format`：如果未提供，使用 `markdown`
2. 基于解析后的参数（含默认值）继续执行...

参数验证：让 Skill 在错误输入时优雅失败

枚举值验证

## 执行步骤
1. 解析 `--focus` 参数（如果提供）。
验证值是否为以下之一：`security`、`performance`、`style`、`all`。
如果值无效，停止并输出：
```
❌ 错误：--focus 的值无效：'{用户输入的值}'
有效值：security | performance | style | all
```
2. 如果 `--focus` 未提供，使用默认值 `all`。

文件路径验证

1. 解析文件路径参数。
2. 验证文件路径：
- 路径是否以 `.ts`、`.js`、`.py` 等受支持的扩展名结尾；
如果不是，警告但仍然继续（"⚠️ 注意：此 Skill 主要针对 TypeScript/JavaScript 文件优化，其他文件类型的分析可能不准确"）
- 使用 Read 工具验证文件是否存在并可读；如果读取失败，报告错误并停止

数值范围验证

1. 解析 `--limit` 参数（要分析的最大文件数）。
- 如果未提供，使用默认值 `10`
- 如果提供，验证是否为正整数且不超过 `50`（超过 50 个文件会导致分析超时）
- 如果超过限制，自动调整为 `50` 并警告："⚠️ 已将 --limit 调整为 50（最大值）"

参数冲突处理

当两个参数逻辑上互斥时，需要明确处理：

## 参数说明
- `--full`：执行完整扫描（会忽略 `--quick` 参数）
- `--quick`：只扫描修改的文件（与 `--full` 互斥）
## 执行步骤
1. 检查是否同时提供了 `--full` 和 `--quick`：
- 如果两者都有，优先使用 `--full`，并提示："⚠️ 同时提供了 --full 和 --quick，将使用 --full（完整扫描）"
- 如果都没有，使用默认值 `--quick`

完整示例：deploy-check Skill（展示完整的参数设计）

---
description: 部署前检查清单，支持多环境和多服务配置
allowed-tools: Bash, Read
---
# 部署前检查
## 目标
在部署到生产或测试环境前，执行自动化检查清单，
确保代码、配置和依赖都处于可部署状态。
## 参数说明（来自 $ARGUMENTS）
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `--env` | enum | 是 | — | 目标环境：`staging` / `production` |
| `--service` | string | 否 | `all` | 要检查的服务名，`all` 表示所有服务 |
| `--skip-tests` | flag | 否 | false | 跳过单元测试检查（快速模式） |
| `--dry-run` | flag | 否 | false | 只报告问题，不执行任何修复操作 |
**调用示例**：

/deploy-check --env production /deploy-check --env staging --service api --skip-tests /deploy-check --env production --dry-run

## 执行步骤
### 步骤 0：参数验证
1. 检查 `--env` 是否提供；如果未提供，停止并输出：
```
❌ 错误：--env 是必填参数
用法：/deploy-check --env <staging|production> [选项]
```
2. 验证 `--env` 值是否为 `staging` 或 `production`；如果无效，报错并停止。
3. 如果 `--env` 为 `production`，输出确认提示：
```
⚠️  你正在检查生产环境部署。请确认你已准备好进行生产部署。
继续执行检查...
```
### 步骤 1：基础检查（所有环境）
- 运行 `git status --porcelain` 检查是否有未提交的修改
- 如果有未提交修改，报告为严重错误（生产环境）或警告（staging）
- 运行 `git log --oneline -1` 确认最新提交
### 步骤 2：测试检查（除非 --skip-tests）
- 如果 `--skip-tests` 未设置：
- 运行 `npm test -- --passWithNoTests 2>&1 | tail -20`
- 检查测试是否全部通过
### 步骤 3：环境配置检查
- 读取 `.env.{env}` 或 `config/{env}.yml` 文件
- 检查必要的环境变量是否都已设置（检查有无占位符如 `TODO` 或空值）
### 步骤 4：生成检查报告
## 输出格式

部署检查报告

目标环境：{env} 目标服务：{service} 检查时间：[时间]

检查结果

结论

[✅ 可以部署] 或 [❌ 发现 N 个问题，不建议部署]

如有问题，请修复后重新运行 /deploy-check

本节记录清单

• [ ] 在你的 Skill 中为每个必填参数添加缺失检查
• [ ] 为所有可选参数在参数说明表中列出默认值
• [ ] 为枚举值参数添加值验证和错误提示
• [ ] 测试参数缺失、参数无效、参数冲突三种情况下 Skill 的行为

下一节：参数验证与错误提示设计——如何让 Skill 的错误提示清晰、有帮助，而不是让用户一头雾水？