Tutorial ｜构建自定义 Command¶

难度：⭐⭐ 时间：~1h 前置：基本 Claude Code 使用产物：自定义 /my-cmd 命令

1. Command 是什么¶

Command = 用户自定义的 slash 命令 - Markdown 文件 - /<cmd-name> 触发 - 可访问 $ARGUMENTS - 可用 frontmatter 配置

vs Skill：Command 路径是 commands/，Skill 路径是 skills/。功能类似，组织不同。

2. 3 步创建 Command¶

2.1 创建文件¶

# 项目级
mkdir -p .claude/commands
cat > .claude/commands/hello.md <<'EOF'
---
description: Say hello
---

# Hello

Greet the user with their name and a fun fact.
EOF

2.2 重启¶

Claude Code 自动加载 commands。

2.3 触发¶

> /hello
# 或
> /hello some args

触发。

3. 实战：6 个 Command¶

3.1 Command 1: Hello¶

---
description: Greet the user
---

# Hello Command

Greet the user by name (if available in session context).
Include a fun fact about programming.
Be brief (3 lines max).

简单。

3.2 Command 2: Code Stats¶

---
description: Show project code statistics
allowed-tools: Bash
---

# Code Stats

Run these commands and report:

\`\`\`bash
find . -name "*.ts" -o -name "*.tsx" | xargs wc -l | tail -1
find . -name "*.ts" -o -name "*.tsx" | wc -l
git log --oneline | wc -l
\`\`\`

Report:
- Total lines of TS code
- Number of TS files
- Number of commits

带 bash。

3.3 Command 3: Refactor¶

---
description: Refactor a file
argument-hint: <file>
---

# Refactor: $ARGUMENTS

1. Read the file
2. Identify code smells (long funcs, dup code, etc.)
3. Suggest 3 refactorings
4. Ask user to choose
5. Implement one at a time
6. Run tests

带 arg hint。

3.4 Command 4: Test Coverage¶

---
description: Check test coverage for a file
allowed-tools: Bash, Read
---

# Test Coverage

For the file $ARGUMENTS:

1. Find related test file(s)
2. Identify untested functions
3. Generate test cases
4. Place in conventional test location
5. Show coverage before/after

测覆盖。

3.5 Command 5: Commit¶

---
description: Generate commit message and commit
allowed-tools: Bash
---

# Commit

1. Check git status
2. Check git diff
3. Generate commit message:
   - type (docs/feat/fix/chore)
   - subject (50 chars)
   - body (what + why)
4. NO Co-Authored-By Claude
5. Ask user to confirm
6. Commit

commit 工具。

3.6 Command 6: PR Description¶

---
description: Generate PR description
allowed-tools: Bash
---

# PR Description

1. Check current branch
2. Get diff from main
3. Get commit list
4. Generate PR description:
   - Summary
   - Changes
   - Test plan
5. Output to user (don't auto-create PR)

PR 工具。

4. Frontmatter 字段¶

---
description: <what it does>             # 必填
argument-hint: <args>                    # 可选
allowed-tools: Bash, Read               # 可选
model: sonnet                            # 可选
---

4 字段。

4.1 description¶

必填。决定什么时候显示在 / 命令列表中。

4.2 argument-hint¶

argument-hint: <file> [options]

提示用户参数。

4.3 allowed-tools¶

allowed-tools: Bash, Read

白名单 —— 防止 command 滥用工具。

4.4 model¶

model: haiku  # 快速
model: opus   # 强

指定模型。

5. 变量¶

5.1 `$ARGUMENTS`¶

Run: $ARGUMENTS

全部参数。

5.2 `$1`, `$2`, ...¶

File: $1
Output: $2

位置参数。

5.3 `@file`¶

Read @README.md and summarize.

文件引用。

6. 3 层 Command 分发¶

6.1 个人级¶

~/.claude/commands/

个人。

6.2 项目级¶

.claude/commands/

项目。

6.3 Plugin 内¶

<plugin>/commands/

Plugin。

7. 高级：含代码块¶

---
description: Deploy the project
allowed-tools: Bash
---

# Deploy

## Pre-check
!bash
\`\`\`bash
git status
\`\`\`

## Build
!bash
\`\`\`bash
npm run build
\`\`\`

## Deploy
!bash
\`\`\`bash
npm run deploy
\`\`\`

多步骤。

8. 调试¶

8.1 不出现¶

检查路径
重启
检查 markdown 格式

8.2 触发报错¶

检查 description
看 stderr

8.3 输出不对¶

简化命令
加输出格式约束

9. 5 个最佳实践¶

description 清晰 —— 显示在 / 列表
单次一个目的 —— 不臃肿
allowed-tools 严格 —— 白名单
测试 —— 用 /cmd 测试
版本控制 —— commit 命令文件

5 条。

10. Command vs Skill 何时用¶

用 Command	用 Skill
简单 prompt	复杂 workflow
一次性	可复用模板
用户触发	LLM 自动触发（描述匹配）
短	长 + 多步骤

何时用。

11. 完整示例：Refactor Command¶

---
description: Refactor a file with specific patterns
argument-hint: <file-path>
allowed-tools: Read, Edit, Bash
model: sonnet
---

# Refactor: $ARGUMENTS

Steps:

1. Read the file
2. Identify refactorings:
   - Functions > 50 lines → extract
   - Nested > 3 levels → flatten
   - Magic numbers → constants
   - Duplicated code → DRY
   - Long params → object
3. Present 3 highest-impact refactorings
4. Ask user to choose
5. Apply one refactoring
6. Run tests: !`npm test`
7. If pass, continue. Else, revert.

完整实战。

12. 下一步¶

写第一个 command
用 /<name> 测试
调优

Tutorial ｜ 构建自定义 Command¶