args 参数基础
High Contrast
Dark Mode
Light Mode
Sepia
Forest
3 min read580 words

args 参数基础

没有参数的 Skill 只能做固定的事。一旦你加入参数，同一个 Skill 就能适应不同的场景：同样的 /review-pr，可以审查不同的分支，关注不同的安全维度，输出不同的详细程度。

参数的传递方式

用户在调用 Skill 时可以用以下几种方式传递参数：

位置参数

/analyze-file src/auth.ts
/review-pr feature/payment

位置参数按顺序传入，在 Skill 提示词中通过 $ARGUMENTS 或具体描述引用。

具名参数

/review-pr --branch feature/payment --focus security
/deploy-check --env staging --service api --dry-run

具名参数更明确，适合有多个参数的场景。

组合参数

/analyze-file src/auth.ts --depth detailed --format json

位置参数 + 具名参数的组合，第一个参数是文件路径，后续是配置选项。

在 Skill 中引用参数

Claude Code 会把用户传入的参数注入到 Skill 的提示词上下文中，你在 Skill 文件中通过以下方式引用：

方式一：$ARGUMENTS 占位符

---
description: 分析指定文件的代码质量
allowed-tools: Read, Grep
---
# 文件代码分析
## 目标
分析用户指定的文件，进行代码质量评估。
## 用户输入
用户传入的参数：$ARGUMENTS
## 执行步骤
1. 解析 $ARGUMENTS 获取文件路径（第一个参数）和选项
2. 使用 Read 工具读取该文件
3. 根据 --focus 参数（如果提供）决定分析重点：
- security：关注安全漏洞
- performance：关注性能问题
- style：关注代码风格
- （未提供时）：全面分析

当用户运行 /analyze-file src/auth.ts --focus security 时，$ARGUMENTS 会被替换为 src/auth.ts --focus security，Claude 根据这个字符串解析参数。

方式二：在执行步骤中描述参数解析逻辑

## 参数说明
此 Skill 接受以下参数（通过 $ARGUMENTS 传入）：
- **第一个参数**（必填）：要分析的文件路径，例如 `src/api/auth.ts`
- **`--focus`**（可选）：分析重点，可选值：`security`、`performance`、`style`，默认全面分析
- **`--output`**（可选）：输出格式，可选值：`brief`（简洁）、`detailed`（详细），默认 `brief`
## 执行步骤
1. 从 $ARGUMENTS 中解析文件路径（第一个参数）
2. 检查文件路径是否存在，如果不存在，提示用户"文件 [路径] 不存在"并停止
3. 根据 --focus 参数决定分析重点...

参数设计原则

原则一：必填参数放前面，可选参数用具名

✅ 好的设计：
/review-pr feature/auth          （必填：分支名，作为位置参数）
/review-pr feature/auth --focus security  （可选：具名参数）
❌ 差的设计：
/review-pr --branch feature/auth --required-focus security
（把必填参数也做成具名参数，调用繁琐）

原则二：为可选参数设计有意义的默认值

## 参数说明
- **`--env`**：目标环境，可选值：`staging`、`production`，默认 `staging`
- **`--depth`**：分析深度，可选值：`quick`（2分钟内）、`full`（全面扫描），默认 `quick`
- **`--format`**：输出格式，可选值：`text`、`json`、`markdown`，默认 `markdown`

原则三：保持参数数量合理

✅ 好的 Skill：2–4 个参数
❌ 过于复杂：8+ 个参数（考虑拆分成多个 Skill）

完整示例：review-pr Skill（带完整参数设计）

---
description: 对指定 PR 或当前分支进行代码审查
allowed-tools: Bash, Read, Grep
---
# PR 代码审查
## 目标
对指定分支或当前分支的最新改动进行代码审查，
输出结构化的审查报告，重点关注用户指定的审查维度。
## 参数说明（来自 $ARGUMENTS）
| 参数 | 类型 | 是否必填 | 说明 | 默认值 |
|------|------|---------|------|--------|
| `--branch` | string | 否 | 要审查的分支名 | 当前分支 |
| `--focus` | enum | 否 | 审查重点：`security` / `performance` / `style` / `all` | `all` |
| `--depth` | enum | 否 | 审查深度：`quick`（只看修改文件）/ `full`（含依赖分析）| `quick` |
**调用示例**：
- `/review-pr` （审查当前分支，全面快速审查）
- `/review-pr --branch feature/payment --focus security`
- `/review-pr --branch main --depth full`
## 执行步骤
1. 解析 $ARGUMENTS：
- 获取 `--branch` 值（如未提供，运行 `git branch --show-current` 获取当前分支）
- 获取 `--focus` 值（默认 `all`）
- 获取 `--depth` 值（默认 `quick`）
2. 获取要审查的变更：
- 运行 `git diff main...{branch} --name-only` 获取修改的文件列表
- 如果 `--depth` 为 `quick`，只分析直接修改的文件
- 如果 `--depth` 为 `full`，还需分析这些文件的导入依赖
3. 对每个修改的文件，按照 `--focus` 参数进行分析：
- `security`：重点检查 SQL 注入、XSS、硬编码密钥、不安全的 HTTP
- `performance`：重点检查 N+1 查询、不必要的循环、内存泄漏风险
- `style`：重点检查命名规范、函数长度、注释质量
- `all`：以上三类都检查
4. 生成报告
## 输出格式

PR 审查报告：{branch}

审查时间：[当前时间] 修改文件数：N 审查重点：{focus}

🔴 严重问题（必须修复）

🟡 改进建议（建议修复）

✅ 通过检查

审查覆盖 N 个文件，{depth} 模式

本节记录清单

下一节：必填与可选参数、默认值设计——如何处理参数缺失的情况？如何为参数设置合理的默认值和验证逻辑？