Commands系统完整指南：从 Slash 命令到 Skills 工作流的全面精通

课程信息

• 作者：老金
• GitHub：https://github.com/KimYx0207
• 公众号：老金带你玩AI
• X（Twitter）：老金带你玩AI
• 个人博客：https://aiking.dev
• 预计学时：4-6小时
• 难度等级：⭐⭐ 入门级
• 更新日期：2026年6月9日
• 适用版本：Claude Code v2.1.169（验证于 2026-06-09；v2.1.158 以前差量保留为历史基线）
• 信息来源：内置命令参考 | Skills 官方文档 | Claude Command Suite | 最佳实践
• 前置要求：已完成Claude Code安装和基础使用

本课学习目标

我在公众号“老金带你玩AI”里反复强调一件事：命令不是炫技，命令要能把真实工作收口。

完成本课学习后，你将能够：

1. 理解Commands本质：掌握Slash命令就是Markdown提示词的核心概念
2. 5分钟创建第一个命令：从零开始创建并运行自定义命令
3. 分清 legacy commands 与 Skills：知道什么时候继续用 .claude/commands/，什么时候应该迁移到 Skills
4. 掌握内置命令的新表面：了解 /plan、/plugin、/release-notes、/rewind、/insights、/schedule、/statusline
5. 组合命令构建工作流：将多个命令串联成自动化流程
6. 排查命令故障：独立解决90%的常见配置和执行问题
7. 掌握frontmatter配置：使用description、allowed-tools、model等高级配置
8. 精通$ARGUMENTS参数：接收和解析用户输入参数

前置知识：本教程假设你已掌握02教程中的30+内置命令用法，重点讲解自定义命令开发。

学习路径导航（先看这里！）

根据你的情况选择学习路径：这是一篇长教程，不用全看！根据你的目标选择路径。

路径A：5分钟快速上手

适合人群：急着体验自定义命令，想快速跑起来

只看这些章节（其他跳过）：

✅ 术语表（3分钟）
✅ 第二部分：5分钟快速开始（5分钟）

5分钟后你能达到：成功创建第一个自定义命令并运行

路径B：完整学习（3-4小时）

适合人群：想系统掌握Commands系统，成为命令开发高手

学习顺序：从头到尾所有章节

建议分段学习：

• 第1天（30分钟）：第1-3部分（简介+快速开始+内置命令速查）
• 第2天（1.5小时）：第4部分（自定义命令开发）⭐ 核心内容
• 第3天（1小时）：第5部分（高级用法）
• 第4天（0.5小时）：第6-7部分（FAQ+附录）

注意：内置命令的详细用法已在「02-基础使用完整指南」中讲解，本教程重点是自定义命令开发！

路径C：问题速查（5分钟）

适合人群：命令不工作，需要快速解决

直接跳到：

第六部分：FAQ - 20个常见问题解答
第五部分5.5节：故障排查

使用方法：

1. 按 Ctrl + F 搜索你的问题关键词
2. 找到对应的Q&A
3. 按步骤解决

路径D：专项学习（30-60分钟/主题）

适合人群：已经会基础命令，想深入某个功能

术语表（小白必读）

在开始之前，先了解这些关键术语。用生活类比帮助理解：

补充说明：小白必看的几个概念

1. YAML格式是什么？

YAML是一种简单的配置文件格式，用"键: 值"的形式记录信息：

# 这是一个YAML示例
name: 老金 # 键是name，值是老金
age: 30 # 键是age，值是30
skills: # skills是一个列表
  - Python # 列表项用 - 开头
  - JavaScript

生活类比：YAML就像你的个人简历表格，"姓名: 张三"这种格式，人能看懂，电脑也能读懂。

2. ~ 符号是什么？

~（波浪号）是你的"用户主目录"的简写：

• Windows：~ = C:\Users\你的用户名（比如 C:\Users\admin）
• macOS：~ = /Users/你的用户名
• Linux：~ = /home/你的用户名

示例：~/.claude/commands/ 的意思是：

• Windows → C:\Users\admin\.claude\commands\
• macOS → /Users/laojin/.claude/commands/

3. heredoc语法是什么？

heredoc是一种"多行文本写入"的语法，可以一次性把多行内容写入文件，不用一行一行写。

⚠️ 重要提醒：heredoc是在PowerShell/Bash终端里用的，不是在Claude Code对话框里用的！

如果你已经在Claude Code里，根本不需要学heredoc，直接说人话让Claude帮你创建文件就行：

帮我创建文件 .claude/commands/hello.md，内容是：
# 问候命令
你好！请问候用户：$ARGUMENTS

Claude Code会自动帮你创建文件夹和文件！

PowerShell终端版本（在Windows PowerShell窗口里用）：

@'
这里是第一行
这里是第二行
这里是第三行
'@ | Out-File -FilePath "文件路径"

Bash终端版本（在macOS/Linux终端里用）：

cat > 文件路径 << 'EOF'
这里是第一行
这里是第二行
这里是第三行
EOF

生活类比：heredoc就像"复制粘贴"——把一大段文字一次性塞进文件里。

小技巧：在Claude Code对话框里换行用 Shift + Enter，按 Enter 会直接发送消息。

第一部分：Commands简介

1.1 什么是Slash命令

一句话理解：Slash命令就是Claude Code的"快捷方式"，输入 /命令名就能触发预设的操作。

生活类比：

• 没有Slash命令：每次点外卖都要重新输入地址、选择口味、备注
• 有Slash命令：保存一个"我的常用订单"，一键下单

核心概念（官方文档验证）：

自定义命令 = .claude/commands/目录下的Markdown文件
命令名 = 文件名（不含.md后缀）
命令内容 = Markdown文件的内容（作为提示词注入）
参数 = $ARGUMENTS变量接收用户输入

当你输入 /write AI教程
Claude Code做的事：
1. 找到 .claude/commands/write.md 文件
2. 读取文件内容作为提示词
3. 把"AI教程"赋值给 $ARGUMENTS
4. 执行这个提示词

1.2 命令的三大类型

Claude Code的命令分为三大类：

命令来源决策树：

你需要什么功能？
    │
    ├── 会话管理、系统诊断？
    │       └── 用内置命令（/clear、/doctor等）
    │
    ├── 项目特定且要长期维护的工作流？
    │       └── 优先创建项目级 Skills
    │
    ├── 只是给当前项目包一层轻量 slash 入口？
    │       └── 用 `.claude/commands/` 兼容方式也可以
    │
    └── 所有项目通用的工具？
            └── 创建用户级 Skills 或用户级兼容命令

1.3 为什么要学Commands

没有Commands之前：

你：帮我写一篇公众号文章，主题是AI工具
    要求：
    1. 风格要接地气
    2. 字数1500-2000
    3. 包含实战案例
    4. 开头要有金句
    5. 结尾要有行动号召
    ...（每次都要重复说一遍）

10分钟后...

你：帮我写另一篇，主题是Claude Code
    要求：（又要重复一遍...）

有了Commands之后：

你：/write AI工具

Claude自动知道：
- 风格要接地气
- 字数1500-2000
- 包含实战案例
- 开头要有金句
- 结尾要有行动号召

直接开始写作！

Commands的核心价值：

第二部分：5分钟快速开始

本节目的：用最快速度创建第一个自定义命令，让你立即看到效果！

预计时间：5分钟

2.1 创建第一个自定义命令

步骤1：创建命令目录

Windows系统（PowerShell）：

# 进入你的项目目录
cd C:\你的项目路径
 
# 创建commands目录
New-Item -ItemType Directory -Path ".claude\commands" -Force

macOS/Linux系统：

# 进入你的项目目录
cd ~/你的项目路径
 
# 创建commands目录
mkdir -p .claude/commands

验证是否成功：

# 检查目录是否存在
ls .claude/commands
# 应该显示空目录（暂时没有文件）

步骤2：创建最简单的命令文件

创建文件 .claude/commands/hello.md：

💡 你有两种选择：

选择A：在Claude Code对话框里说人话（推荐新手）

帮我创建文件 .claude/commands/hello.md，内容是：

# 问候命令

你好！我是你的AI助手。

用户想要问候的对象是：$ARGUMENTS

如果没有提供名字，请使用"朋友"作为默认称呼。

请用热情友好的方式问候，并询问今天可以帮助什么。

（换行用 Shift + Enter，最后按 Enter 发送）

选择B：在终端里用命令行（熟悉命令行的用户） 见下方PowerShell/Bash代码

Windows（PowerShell终端）：

@'
# 问候命令
 
你好！我是你的AI助手。
 
用户想要问候的对象是：$ARGUMENTS
 
如果没有提供名字，请使用"朋友"作为默认称呼。
 
请用热情友好的方式问候，并询问今天可以帮助什么。
'@ | Out-File -FilePath ".claude\commands\hello.md" -Encoding utf8

macOS/Linux（终端）：

cat > .claude/commands/hello.md << 'EOF'
# 问候命令
 
你好！我是你的AI助手。
 
用户想要问候的对象是：$ARGUMENTS
 
如果没有提供名字，请使用"朋友"作为默认称呼。
 
请用热情友好的方式问候，并询问今天可以帮助什么。
EOF

步骤3：测试命令

启动Claude Code并测试：

# 启动Claude Code
claude

在交互模式中输入：

You: /hello 张三

预期结果：

你好，张三！很高兴见到你！

今天有什么我可以帮助你的吗？无论是写代码、解答问题，
还是其他任何事情，我都随时准备为你效劳！

再测试无参数情况：

You: /hello

预期结果：

你好，朋友！很高兴见到你！

今天有什么我可以帮助你的吗？

2.2 恭喜完成第一个命令！

你刚才完成了什么？

1. 创建了命令目录 .claude/commands/
2. 编写了第一个命令文件 hello.md
3. 使用 $ARGUMENTS 接收参数
4. 成功运行命令并看到效果

核心要点回顾：

命令文件 = Markdown文件
命令名 = 文件名（不含.md）
参数 = $ARGUMENTS 变量

/hello 张三
  │      │
  │      └── $ARGUMENTS = "张三"
  └── 读取 hello.md

第三部分：内置命令速查（做完练习后再查）

2026-05-30 版本差异速览（v2.1.158）：当前稳定版新增 Opus 4.8 与 /effort xhigh，/workflows 可查看 dynamic workflows 后台编排，claude agents 支持用 ! <command> 或 claude --bg --exec '<command>' 启动可附着/可分离的后台 shell 会话。v2.1.157 还补了 /plugin 参数补全、/terminal-setup 对 IDE 终端 GPU 加速的处理，以及 workflow 关键词触发开关；/simplify 现在是清理型 review，不再等同于完整 /code-review --fix，代码缺陷审查仍以 /code-review 为主路径。

本节说明：这一节是参考表，不建议第一次学习时逐行阅读。你已经在第二部分创建过一个能运行的命令；如果目标是继续实操，可以直接跳到「第四部分：自定义命令开发」。需要查命令时再回来看这张表。

详细教程：请回顾「02-基础使用完整指南.md」→ 第四部分：Slash命令大全

版本校准（2026-04）：当前官方 Commands Reference 没有 /todos。Claude 的待办追踪是内部 TodoWrite 工具 / SDK 事件；后台任务管理使用 /tasks。

内置命令速查表

💡 提示：输入 / 然后按 Tab 键可以查看所有可用命令。

v2.1.69+ 到 v2.1.158 的常用命令增量 🆕

以下命令是 Claude Code 在 2.1.69 之后持续扩展、到 v2.1.158 仍然值得优先掌握的一批能力：

• /powerup：交互式课程（v2.1.90，官方 release 原文：interactive lessons teaching Claude Code features with animated demos）
• /goal：设置完成条件，Claude 会跨 turns 持续推进，直到达成目标、遇到限制或被你停止
• /scroll-speed：调节鼠标滚动速度，适合长 diff、长日志和 transcript 浏览
• /loop：bundled skill 形式的定时循环任务
• /effort：推理深度控制（五级：low/medium/high/xhigh/max）
• /sandbox：沙箱隔离
• /color：会话颜色
• /copy：复制回复
• /branch：会话分支
• /plan：先规划后执行
• /plugin：插件市场与安装入口
• /release-notes：更新日志（v2.1.92 起为 interactive version picker，见官方 release）
• /cost：费用与用量（v2.1.92 起对 subscription users 增加 per-model and cache-hit breakdown，见官方 release）
• /rewind：回退到更早会话状态
• /insights：查看会话和使用洞察
• /schedule：计划性任务入口
• /statusline：状态行定制
• /skills：查看和搜索已安装的 Skills（支持关键词过滤）
• /proactive：/loop 的别名（v2.1.105+）
• /usage：v2.1.149+ 会按 skills、subagents、plugins、MCP server 等类别拆分用量
• /diff：v2.1.149+ 详情视图支持方向键、j/k、PgUp/PgDn、Space、Home/End 滚动
• /model：v2.1.153+ 选择会保存为新会话默认模型；需要“只改当前会话”时按当前 picker 的提示操作
• /doctor：v2.1.153+ 会显示上一次更新尝试结果；npm 全局安装无法自动更新时会给出修复提示
• /code-review：v2.1.146/147 起替代 /simplify，可写 /code-review high；PR 场景可用 --comment 生成 inline GitHub comment
• /workflows：v2.1.154+ 查看 dynamic workflows；适合让 Claude 把复杂任务拆给大量后台 agent 时观察进度
• claude agents 中的 ! <command>：v2.1.154+ 可把 shell 命令作为后台 session 运行，等同于命令行的 claude --bg --exec '<command>'
• /reload-skills：v2.1.152+ 重新扫描 Skill 目录，配合 SessionStart.reloadSkills 可让 Hook 安装的 Skill 在同一会话内可用
• /plugin：v2.1.157+ 对子命令、已安装插件名和已知 marketplace 插件提供参数补全
• /terminal-setup：v2.1.157+ 会在 VS Code / Cursor / Windsurf 集成终端里禁用 GPU 加速，减少乱码渲染
• /config：v2.1.157+ 可关闭 workflow 关键词触发，避免普通提示里的 “workflow” 误触发 dynamic workflow
• Vim NORMAL 模式下 /：v2.1.152+ 打开反向历史搜索，和 bash/zsh vi-mode 更接近
• Markdown 输出：v2.1.149+ GFM task list checkbox 会按勾选框渲染，不再只是普通项目符号

/powerup - 交互式功能教程（v2.1.90+）

官方说明（v2.1.90）：Added /powerup — interactive lessons teaching Claude Code features with animated demos。

用法：在 REPL 中执行 /powerup，按界面提示学习即可；具体步骤与课时结构以当前版本 CLI 为准，此处不臆造菜单文案。

You: /powerup

/loop - 定时循环执行（bundled skill）

一句话理解：就像设了一个"定时闹钟"——每隔一段时间自动执行你指定的任务。

/loop 5m check deployment status  # 每5分钟检查部署状态
/loop 30s run tests               # 每30秒运行测试
/loop 1h check for updates        # 每1小时检查更新
/loop check the build             # 不写间隔时由 Claude 动态选择

语法：/loop [时间间隔] [提示词]

时间格式：数字 + 单位（s秒 / m分钟 / h小时）。如果省略时间间隔，Claude 会根据任务动态选择合适的检查频率。

注意事项：

• 只在 REPL 空闲时触发（不会打断你当前的工作）
• 官方当前文档里，循环任务是 7 天后自动过期
• 等待下一次迭代时，可按 Esc 取消当前循环
• /proactive 是 /loop 的别名

💡 实用场景：监控CI/CD部署进度、定期检查构建状态、轮询外部服务健康状况。

/effort - 推理深度控制

一句话理解：调整Claude的"思考深度"——简单问题快速回答，复杂问题深入分析。

/effort low     # ○ 快速简洁
/effort medium  # ◐ 平衡模式
/effort high    # ● 深度推理
/effort xhigh   # ◉ 深度推理（推荐 Opus 4.7 默认）
/effort max     # ⬤ 极限推理
/effort auto    # 重置为自动判断

💡 省钱技巧：批量处理简单任务时切换到 low，关键决策时切换到 xhigh。

💡 交互式滑块：直接输入 /effort（不带参数）会弹出交互式滑块，拖动选择级别。

💡 其他设置方式：claude --effort xhigh（CLI 参数）或 CLAUDE_CODE_EFFORT_LEVEL=xhigh（环境变量）。

/sandbox - 沙箱隔离模式

一句话理解：给Claude套上"安全围栏"——限制它能读写哪些文件、能不能访问网络。

/sandbox        # 启用OS级沙箱隔离

隔离能力：

• 文件系统隔离：限制可读写的目录范围
• 网络隔离：限制外部网络访问
• 进程隔离：OS级别的沙箱保护

在 settings.json 中可以精细配置：

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["/tmp", "./src"],
      "allowRead": ["./", "/usr/lib"],
      "denyRead": [".env", "credentials.json"]
    }
  }
}

⚠️ 安全提示：处理不信任的代码或敏感项目时，强烈建议启用沙箱模式。

/color - 会话颜色设置

/color blue     # 设置会话窗口颜色为蓝色
/color default  # 重置为默认颜色

💡 多窗口区分：同时开多个Claude Code会话时，用不同颜色区分（比如：蓝色=前端、绿色=后端）。

/copy N - 复制AI回复

/copy           # 复制最新一条AI回复到剪贴板
/copy 3         # 复制第3条AI回复到剪贴板

/branch - 会话分支

/branch         # 从当前位置创建会话分支

一句话理解：就像Git分支——在当前对话点"分叉"，探索不同方案而不影响原对话。

💡 提示：这是原 /fork 命令的重命名版本。适合在关键决策点创建分支，分别尝试方案A和方案B。

第四部分：自定义命令开发

本节目的：掌握自定义命令开发的完整技能

预计时间：90分钟

4.1 命令文件结构

一个完整的命令文件包含两个部分：frontmatter配置区 + Markdown正文。

完整结构示例：

---
description: 公众号文章创作命令
argument-hint: <主题关键词>
allowed-tools:
  - Read
  - Write
  - WebSearch
model: claude-sonnet-4-6
---
 
# 公众号文章创作
 
你是一位资深的公众号写作专家。
 
## 任务
 
根据用户提供的主题创作一篇公众号文章。
 
主题：$ARGUMENTS
 
## 写作要求
 
1. 风格：接地气、说人话
2. 字数：1500-2000字
3. 结构：金句开头 → 核心内容 → 行动号召
 
## 执行步骤
 
1. 使用WebSearch搜索主题相关的最新信息
2. 构思文章大纲
3. 撰写完整文章
4. 使用Write工具保存到articles目录

4.2 命令存放位置与作用域

两种作用域

优先级规则

当同名命令存在于多个位置时，按以下优先级：

1. 项目级（最高）: .claude/commands/
2. 用户级: ~/.claude/commands/
3. 内置命令（最低）

⚠️ 重要澄清：核心系统命令（如 /clear、/help、/compact、/doctor 等）是受保护的，不能被自定义命令覆盖。上述优先级规则仅适用于非核心内置命令。

示例：

假设存在：

• .claude/commands/deploy.md（项目级）
• ~/.claude/commands/deploy.md（用户级）
• 另一个同名的共享 skill /deploy

执行 /deploy 时，优先使用项目级的 deploy.md。

但是：创建 .claude/commands/clear.md 不会覆盖内置的 /clear 命令。

目录结构建议

.claude/commands/
├── 01-write.md          # 核心写作命令
├── 02-write-auto.md     # 自动写作
├── 11-hotspot.md        # 热点扫描
├── 21-title-gen.md      # 标题生成
├── 22-title-score.md    # 标题评分
├── dev/                 # 开发类命令（子目录）
│   ├── code-review.md
│   └── debug.md
└── test/                # 测试类命令
    └── generate-tests.md

命名空间：使用子目录时，命令名变成 /dev:code-review 格式。

4.3 frontmatter配置详解

frontmatter是命令文件开头的YAML配置区，用 --- 包围。

所有可用配置项

---
# === 官方支持的配置项 ===
 
# 命令描述（显示在命令列表中）
description: 这是命令的一句话描述
 
# 参数提示（输入/命令后显示的占位符）
argument-hint: <必需参数> [可选参数]
 
# 允许使用的工具（限制命令可调用的工具）
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - WebSearch
  - Glob
  - Grep
 
# 指定使用的模型
model: claude-sonnet-4-6
 
 
# 禁用模型调用（用于纯文本替换命令）
# disable-model-invocation: true
 
# === 非官方字段（可选，用于自己管理）===
# 注意：以下字段不会被Claude Code解析，仅供人类阅读
# version: 1.0.0   # 用于版本管理
# author: 老金     # 用于标注作者
---

⚠️ 注意：version 和 author 不是Claude Code官方支持的frontmatter字段，但你可以添加它们用于自己的管理目的（Claude Code会忽略未知字段）。

配置项详解

1. description（命令描述）

description: AI热点自动扫描 - 抓取今日AI热点并评估爆款潜力

作用：在 /help 和Tab补全时显示，帮助用户了解命令功能。

2. argument-hint（参数提示）

argument-hint: <主题> [--style=formal] [--length=2000]

作用：输入 /命令名 后显示的占位符提示。

3. allowed-tools（允许的工具）

allowed-tools:
  - Read
  - Write
  - WebSearch

作用：限制命令只能使用指定的工具，提高安全性。

可用工具列表：

💡 提示：最常用的工具是 Read、Write、Edit、Bash、WebSearch。其他工具按需使用。

4. model（指定模型）

model: claude-opus-4-6

作用：强制使用指定模型执行命令（覆盖当前会话模型）。

5. disable-model-invocation（禁用模型调用）

disable-model-invocation: true

作用：当设置为true时，命令只进行简单的文本替换，不会触发AI模型推理。

适用场景：

• 纯文本模板命令（快速插入固定内容）
• 变量替换命令（$ARGUMENTS 直接替换）
• 节省Token和响应时间

示例：

---
description: 快速插入版权声明
disable-model-invocation: true
---
 
© 2025 $ARGUMENTS. All rights reserved.

执行 /copyright 老金 会直接输出 © 2025 老金. All rights reserved.，不经过AI处理。

4.4 $ARGUMENTS参数处理

$ARGUMENTS 是Claude Code的内置变量，接收用户在命令后输入的所有内容。

基本用法

# 问候命令
 
用户要问候的对象是：$ARGUMENTS
 
如果没有提供名字，使用"朋友"作为默认称呼。

调用示例：

/hello 张三
→ $ARGUMENTS = "张三"

/hello
→ $ARGUMENTS = ""

多参数解析

# 文章生成命令
 
## 参数格式
 
$ARGUMENTS 格式：<主题> [风格] [字数]
 
解析规则：
 
- 第一个参数：主题（必需）
- 第二个参数：风格（可选，默认"接地气"）
- 第三个参数：字数（可选，默认1500）
 
## 示例
 
/write AI工具 技术 3000
→ 主题=AI工具, 风格=技术, 字数=3000
 
/write Claude Code
→ 主题=Claude Code, 风格=接地气, 字数=1500

参数验证

# 代码审查命令
 
## 输入验证
 
首先检查 $ARGUMENTS：
 
**如果为空**：
提示用户：请提供文件路径，格式：/scan-code <文件路径>
终止执行
 
**如果不是有效路径**：
提示用户：路径无效，请检查文件是否存在
终止执行
 
**如果验证通过**：
继续执行审查流程

4.5 工具调用语法

自定义命令可以调用Claude Code的所有工具。

基础工具调用

## 执行步骤
 
### 步骤1：读取配置文件
 
使用Read工具读取项目配置：
 
```
Read(".claude/settings.json")
```
 
### 步骤2：搜索TODO注释
 
使用Grep搜索所有TODO：
 
```
Grep("TODO|FIXME", path="src/", type="py")
```
 
### 步骤3：运行测试
 
使用Bash执行测试命令：
 
```bash
npm run test
```

MCP工具调用

💡 什么是MCP？

MCP（Model Context Protocol）是Claude Code的"外部工具扩展系统"。

通俗解释：MCP就像手机的"应用商店"——你可以安装各种第三方工具（如搜索引擎、数据库查询、GitHub操作等），让Claude Code拥有更多能力。

命名规则：mcp__服务器名__工具名 比如 mcp__mcp-router__search 就是调用mcp-router服务器的search工具。

详细教程：MCP的安装和配置请见「04-MCP集成完整指南」。

## MCP工具使用
 
### 搜索最新信息
 
```
mcp__mcp-router__search(
    query="$ARGUMENTS 最新资讯",
    search_service="google",
    max_results=10
)
```
 
### 获取GitHub趋势
 
```
mcp__mcp-router__trending(
    search_service="github",
    max_results=20
)
```

4.6 条件逻辑设计

虽然Markdown不支持编程逻辑，但通过精心设计的提示词可以实现条件分支。

IF-ELSE模式

## 执行逻辑
 
根据 $ARGUMENTS 的内容判断执行路径：
 
**情况1：参数包含"深度"或"详细"**
→ 执行深度分析流程
→ 输出完整报告（3000字以上）
→ 包含数据图表
 
**情况2：参数包含"快速"或"简要"**
→ 执行快速分析
→ 输出简要报告（500字以内）
→ 只包含关键结论
 
**情况3：其他情况（默认）**
→ 执行标准分析
→ 输出标准报告（1500字）
→ 包含主要发现和建议

SWITCH-CASE模式

## 类型判断
 
检查 $ARGUMENTS 的第一个关键词，确定文章类型：
 
| 关键词 | 文章类型 | 使用模板                |
| ------ | -------- | ----------------------- |
| "测评" | 测评类   | templates/review.md     |
| "教程" | 教程类   | templates/tutorial.md   |
| "降价" | 降价类   | templates/discount.md   |
| "对比" | 对比类   | templates/comparison.md |
| 其他   | 通用类   | templates/general.md    |
 
根据判断结果，加载对应模板。

4.7 实战案例：创建写作命令

目标：创建一个完整的公众号写作命令

文件：.claude/commands/write.md

frontmatter配置

---
description: 公众号文章全自动创作 - 从选题到成稿的完整流程
argument-hint: <主题关键词>
allowed-tools:
  - Read
  - Write
  - WebSearch
  - Grep
  - Bash
---

角色定义和任务

# 公众号文章创作系统
 
## 角色定义
 
你是一位资深的公众号写作专家，擅长创作接地气、有深度的技术科普文章。
 
## 任务
 
根据用户提供的主题，创作一篇高质量的公众号文章。
 
**主题**：$ARGUMENTS

执行流程

步骤1-2：选题检查和信息收集

### 步骤1：选题可行性检查
 
首先判断选题是否适合写作：
 
- 是否有足够的信息支撑？
- 受众是否感兴趣？
- 是否与账号定位匹配？
 
如果不适合，向用户说明原因并建议替代选题。
 
### 步骤2：信息收集
 
使用WebSearch搜索主题相关的最新信息：
WebSearch(query="$ARGUMENTS 最新资讯 2025")
 
收集以下信息：
 
- 核心概念和定义
- 最新动态和更新
- 用户痛点和需求
- 实战案例和数据

步骤3：构思大纲

一、金句开头（1段）
   - 引发共鸣的场景描述
   - 或令人惊讶的数据/事实

二、问题引入（2-3段）
   - 用户面临的痛点
   - 为什么需要关注这个话题

三、核心内容（5-8段）
   - 关键知识点
   - 实战案例
   - 操作步骤（如适用）

四、总结升华（1-2段）
   - 核心观点回顾
   - 行动号召

步骤4-6：撰写、保存、生成标题

### 步骤4：撰写文章
 
按照大纲撰写完整文章，注意：
 
**风格要求**：说人话、用类比、多短句、口语化
**格式要求**：标题≤30字、正文1500-2000字、段落≤150字
 
### 步骤5：保存文章
 
使用Write工具保存文章到 articles/drafts/[日期]\_[主题].md
 
### 步骤6：生成标题
 
为文章生成5个备选标题（包含数字、引发好奇心、≤30字）

输出格式示例

# [选定的标题]

[文章正文]

---
## 备选标题
1. [标题1]
2. [标题2]
3. [标题3]
4. [标题4]
5. [标题5]

使用示例：

You: /write Claude Code入门

# Claude会执行完整流程：
# 1. 检查选题可行性
# 2. 搜索最新信息
# 3. 构思大纲
# 4. 撰写文章
# 5. 保存到drafts目录
# 6. 生成备选标题

第五部分：命令高级用法

本节目的：掌握命令组合、嵌套、社区资源等高级技巧

预计时间：60分钟

5.1 命令命名空间

当命令放在子目录时，使用 目录名:命令名 的格式调用。

目录结构：

.claude/commands/
├── dev/
│   ├── code-review.md    → /dev:code-review
│   ├── debug.md          → /dev:debug
│   └── refactor.md       → /dev:refactor
├── test/
│   ├── generate.md       → /test:generate
│   └── coverage.md       → /test:coverage
└── deploy/
    ├── prepare.md        → /deploy:prepare
    └── rollback.md       → /deploy:rollback

优点：

• 命令分类清晰
• 避免命名冲突
• 便于团队管理

5.2 命令组合与链式调用

在命令中调用其他命令

# 每日工作流命令
 
## 执行步骤
 
### 步骤1：热点扫描
 
首先执行热点扫描，获取今日AI热点：
 
```
执行 /hotspot 命令
```
 
### 步骤2：选择写作主题
 
从热点中选择一个适合的主题。
 
### 步骤3：创作文章
 
使用选定的主题执行写作：
 
```
执行 /write [选定的主题]
```
 
### 步骤4：质量检查
 
文章完成后执行质量检查：
 
```
执行 /pre-check
```

创建工作流命令

---
description: 完整的文章创作工作流
argument-hint: <热点关键词>
---
 
# 文章创作工作流
 
## 工作流步骤
 
### 阶段1：选题
 
1. 执行 /topic-filter $ARGUMENTS
2. 如果选题通过，继续下一步
3. 如果不通过，向用户建议替代选题
 
### 阶段2：创作
 
1. 执行 /write [确认的选题]
2. 等待文章生成完成
 
### 阶段3：优化
 
1. 执行 /title-gen 为文章生成更多标题
2. 执行 /title-score 评估标题质量
3. 选择最佳标题
 
### 阶段4：检查
 
1. 执行 /pre-check 进行发布前检查
2. 如果检查通过，输出最终文章
3. 如果不通过，根据建议修改后重新检查
 
### 阶段5：完成
 
输出最终成果：
 
- 文章文件路径
- 选定的标题
- 质量检查报告
 
```
 
```

5.3 模块化设计

将通用逻辑提取为模块

创建模块文件 .claude/modules/writing-style.md：

# 写作风格规范
 
## 语言风格
 
- 说人话，不说AI腔
- 用"你"而不是"您"
- 用口语化表达代替书面语
- 举例子比讲道理更有效
 
## 句式要求
 
- 短句优先
- 每段不超过150字
- 金句放在段落开头
 
## 禁用词汇
 
- "首先...其次...最后..."
- "综上所述"
- "不言而喻"
- "众所周知"

在命令中引用模块：

# 文章创作命令
 
## 步骤1：加载写作规范
 
首先读取写作风格规范：

Read(".claude/modules/writing-style.md")

## 步骤2：按规范创作
遵循加载的写作规范，创作文章...

5.4 社区命令资源

Claude Command Suite

地址：https://github.com/qdhenry/Claude-Command-Suite

包含内容：

• 148+ 专业命令
• 54 AI代理
• 完整的开发工作流

安装方法：

# 克隆仓库
git clone https://github.com/qdhenry/Claude-Command-Suite.git
 
# 复制需要的命令到你的项目
cp Claude-Command-Suite/.claude/commands/dev/* .claude/commands/dev/

常用命令示例：

Awesome Claude Code

地址：https://github.com/hesreallyhim/awesome-claude-code

包含内容：

• 社区精选命令
• 最佳实践
• 配置模板

5.5 故障排查

命令不存在

症状：Command not found: /my-command

排查步骤：

# 1. 检查文件是否存在
ls .claude/commands/my-command.md
 
# 2. 检查文件名是否正确（区分大小写）
# 命令名 = 文件名（不含.md）
 
# 3. 检查目录位置
# 项目级：.claude/commands/
# 用户级：~/.claude/commands/
 
# 4. 重启Claude Code
exit
claude

命令执行失败

症状：命令触发了但执行出错

排查步骤：

# 1. 检查frontmatter格式
# YAML语法错误会导致命令无法解析
# 使用在线YAML验证器检查
 
# 2. 检查allowed-tools配置
# 如果限制了工具，确保需要的工具在列表中
 
# 3. 检查$ARGUMENTS使用
# 确保参数格式正确

frontmatter解析错误

症状：命令行为异常

常见错误：

# 错误1：缺少结束标记
---
description: 我的命令
# 缺少 ---
 
# 错误2：缩进错误
---
allowed-tools:
- Read    # 应该有缩进
  - Write
---
 
# 正确格式
---
description: 我的命令
allowed-tools:
  - Read
  - Write
---

第六部分：FAQ（20个常见问题）

基础问题

Q1: 自定义命令文件放在哪里？

Q2: 命令名和文件名有什么关系？

命令名 = 文件名（不含.md扩展名）

.claude/commands/write.md → /write
.claude/commands/dev/check.md → /dev:check

Q3: 如何传递参数给命令？

在命令后直接输入参数，用 $ARGUMENTS 接收：

/write AI教程
→ $ARGUMENTS = "AI教程"

Q4: 支持多个参数吗？

支持！所有参数都在 $ARGUMENTS 中，需要在命令中自行解析：

## 参数格式
 
$ARGUMENTS 格式：<主题> [风格] [字数]
 
示例：/write AI工具 技术 3000

Q5: frontmatter是必须的吗？

不是必须的，但强烈推荐。没有frontmatter的命令也能工作：

# 最简单的命令（无frontmatter）
 
你好！请问候用户：$ARGUMENTS

配置问题

Q6: allowed-tools有哪些可选值？

Q7: 如何指定命令使用的模型？

在frontmatter中设置：

---
model: claude-opus-4-6
---

Q8: argument-hint有什么作用？

显示在命令输入时的占位提示：

---
argument-hint: <主题> [--style=formal]
---

输入 /write 后会显示 <主题> [--style=formal]。

Q9: 如何让命令在所有项目都可用？

放在用户级目录：~/.claude/commands/

Q10: 项目级和用户级命令同名怎么办？

项目级优先。优先级顺序：

1. 项目级 .claude/commands/
2. 用户级 ~/.claude/commands/
3. 内置命令

开发问题

Q11: 命令可以调用其他命令吗？

可以！在命令中说明调用哪个命令：

## 步骤3
 
执行 /pre-check 命令检查文章质量

Q12: 如何在命令中使用MCP工具？

直接调用MCP工具函数：

## 搜索信息
 
```
mcp__mcp-router__search(query="$ARGUMENTS")
```

Q13: 命令支持中文名吗？

技术上支持，但不推荐：

✅ /write（推荐）
⚠️ /写作（可能有编码问题）

建议：命令名用英文，description用中文。

Q14: 如何调试命令？

1. 使用简单测试参数运行
2. 检查Claude的执行过程
3. 查看是否有错误提示
4. 逐步简化命令定位问题

Q15: 命令文件有大小限制吗？

没有硬性限制，但建议：

• 单个命令文件不超过500行
• 复杂逻辑拆分为多个命令
• 通用内容提取为模块

故障排查

Q16: 命令不执行怎么办？

检查清单：

• 文件存在于正确位置？
• 文件名正确（含.md扩展名）？
• frontmatter格式正确（YAML语法）？
• 重启过Claude Code？

Q17: frontmatter解析失败怎么办？

常见错误：

1. 缺少开始或结束的 ---
2. YAML缩进错误
3. 特殊字符未转义

使用在线YAML验证器检查。

Q18: 命令执行很慢怎么办？

可能原因：

1. 命令中包含大量搜索操作
2. 读取了大文件
3. 网络请求超时

优化建议：

• 减少不必要的工具调用
• 限制搜索结果数量
• 添加超时处理

Q19: 如何查看可用命令列表？

# 方法1：/help命令
You: /help
 
# 方法2：Tab补全
输入 / 然后按Tab键

Q20: 如何分享命令给团队？

1. 将 .claude/commands/ 加入Git版本控制
2. 团队成员克隆/拉取后自动获得命令
3. 使用统一的命名规范

git add .claude/commands/
git commit -m "Add custom commands"
git push

第七部分：实战练习

本节目的：通过动手练习巩固所学知识

预计时间：60分钟

7.1 练习1：创建问候命令（10分钟）

目标：创建一个带参数验证的问候命令

任务：

1. 创建 .claude/commands/greet.md
2. 实现以下功能：
   • 接收姓名参数
   • 如果没有参数，提示用户输入
   • 根据当前时间（早/中/晚）使用不同问候语

参考答案：

---
description: 智能问候命令 - 根据时间自动选择问候语
argument-hint: <姓名>
---
 
# 智能问候命令
 
## 任务
 
根据当前时间和用户名称，生成个性化问候。
 
## 参数
 
用户名称：$ARGUMENTS
 
## 执行逻辑
 
### 步骤1：验证参数
 
如果 $ARGUMENTS 为空：
 
- 提示用户："请提供姓名，格式：/greet 张三"
- 终止执行
 
### 步骤2：判断时间段
 
- 6:00-11:59 → 早上好
- 12:00-17:59 → 下午好
- 18:00-21:59 → 晚上好
- 22:00-5:59 → 夜深了
 
### 步骤3：生成问候
 
组合问候语和用户名称，友好地问候用户。

测试：

/greet 张三
/greet

7.2 练习2：创建代码审查命令（20分钟）

目标：创建一个代码审查命令

任务：

1. 创建 .claude/commands/code-review.md
2. 实现以下功能：
   • 接收文件路径参数
   • 读取文件内容
   • 检查代码风格、潜在Bug、安全问题
   • 输出结构化审查报告

参考答案：

---
description: 代码审查命令 - 检查代码质量和潜在问题
argument-hint: <文件路径>
allowed-tools:
  - Read
  - Grep
---
 
# 代码审查命令
 
## 任务
 
对指定文件进行代码审查，检查代码质量。
 
## 参数
 
文件路径：$ARGUMENTS
 
## 执行流程
 
### 步骤1：验证参数
 
如果 $ARGUMENTS 为空，提示用户提供文件路径。
 
### 步骤2：读取文件
 
使用Read工具读取文件内容：

Read("$ARGUMENTS")

### 步骤3：执行审查
从以下维度审查代码：

**1. 代码风格**
- 命名规范
- 缩进一致性
- 注释完整性

**2. 潜在Bug**
- 空值检查
- 边界条件
- 异常处理

**3. 安全问题**
- SQL注入风险
- XSS风险
- 敏感信息泄露

**4. 性能问题**
- 循环优化
- 数据结构选择
- 资源释放

### 步骤4：输出报告

## 输出格式

代码审查报告

文件：[文件路径] 审查时间：[当前时间]

总体评分：X/100

严重问题（必须修复）：

• [问题1]：[位置] - [说明]

建议改进：

• [建议1]：[位置] - [说明]

代码亮点：

• [亮点1]

**测试**：

```bash
/code-review src/main.py

7.3 练习3：创建工作流命令（30分钟）

目标：创建一个串联多个命令的工作流

任务：

1. 创建 .claude/commands/daily-flow.md
2. 实现以下功能：
   • 调用热点扫描命令
   • 基于热点选择写作主题
   • 调用写作命令生成文章
   • 调用质量检查命令
   • 输出完整工作报告

参考答案：

---
description: 每日内容创作工作流 - 从热点到成稿一站式完成
argument-hint: [热点关键词（可选）]
allowed-tools:
  - Read
  - Write
  - WebSearch
  - Bash
---
 
# 每日内容创作工作流
 
## 任务
 
执行完整的每日内容创作流程。
 
## 参数
 
可选热点关键词：$ARGUMENTS
 
## 执行流程
 
### 阶段1：热点扫描
 
执行热点扫描，获取今日AI热点。
 
如果提供了关键词 $ARGUMENTS，则重点搜索相关热点。
如果没有提供，则全面扫描。
 
### 阶段2：选题决策
 
从热点中选择最适合写作的主题：
 
- 评估时效性
- 评估受众匹配度
- 评估内容价值
 
输出选题理由。
 
### 阶段3：文章创作
 
使用选定的主题执行写作：
 
- 调用 /write [选定主题]
- 等待文章生成完成
 
### 阶段4：标题优化
 
- 调用 /title-gen 生成更多标题候选
- 选择最佳标题
 
### 阶段5：质量检查
 
- 调用 /pre-check 进行发布前检查
- 如果有问题，进行修复
- 直到检查通过
 
### 阶段6：完成报告
 
输出工作报告：

每日创作工作报告

日期：[日期] 耗时：[总耗时]

选题：[选定的主题] 选题来源：[热点来源]

文章：

• 标题：[最终标题]
• 字数：[字数]
• 文件：[文件路径]

处理结果：

• 检查状态：[已检查 / 需修改]
• 修改说明：[如有修改，写明改动点]
• 下一步：[发布 / 继续修改]

备选标题：

1. [标题1]
2. [标题2]
3. [标题3]

**测试**：

```bash
/daily-flow
/daily-flow Claude Code

附录A：命令速查表

内置命令速查

frontmatter配置速查

---
description: 命令描述（显示在帮助中）
argument-hint: <必需> [可选]
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - WebSearch
  - Glob
  - Grep
model: claude-sonnet-4-6
version: 1.0.0
author: 作者名
---

命令文件模板

---
description: 一句话描述命令功能
argument-hint: <参数说明>
allowed-tools:
  - Read
  - Write
---
 
# 命令标题
 
## 角色定义
 
你是...
 
## 任务
 
根据 $ARGUMENTS 执行...
 
## 执行步骤
 
### 步骤1：检查输入
 
检查 $ARGUMENTS 是否有效...
 
### 步骤2：执行操作
 
使用工具执行...
 
### 步骤3：输出结果
 
返回结果...
 
## 输出格式
 
```
[输出模板]
```
 
---
 
## 附录B：社区资源
 
### 官方资源
 
- [Claude Code官方文档](https://docs.anthropic.com/en/docs/claude-code)
- [Slash Commands文档](https://docs.anthropic.com/en/docs/claude-code/slash-commands)
- [Anthropic最佳实践](https://www.anthropic.com/engineering/claude-code-best-practices)
 
### 社区项目
 
- [Claude Command Suite](https://github.com/qdhenry/Claude-Command-Suite) - 148+专业命令
- [Awesome Claude Code](https://github.com/hesreallyhim/awesome-claude-code) - 社区精选资源
 
### 相关课程
 
- 第1部分：环境与安装 - Claude Code安装配置
- 第2部分：基础使用 - CLI启动和交互模式
- 第4部分：MCP集成 - 外部工具连接
- 第5部分：Hooks系统 - 自动化工作流
- 第6部分：Skills定制 - 技能包开发
 
## 学习总结
 
通过本课学习，你已经掌握：
 
1. **Commands核心概念**：Slash命令就是Markdown提示词文件
2. **自定义命令开发**：frontmatter配置、$ARGUMENTS参数处理、工具调用
3. **高级技巧**：命令命名空间、组合调用、模块化设计
4. **社区资源**：Claude Command Suite等专业命令库
5. **故障排查**：常见问题诊断和解决方法
 
> **温馨提示**：内置命令详细用法请回顾「02-基础使用完整指南」
 
**下一步建议**：
 
1. 从第二部分的简单示例开始实践
2. 根据你的项目需求，创建第一个实用命令
3. 参考第四部分的实战案例，逐步构建命令库
4. 探索社区资源，学习优秀命令的设计模式
 
**记住**：Commands的核心价值是"一次配置，永久使用"。花时间设计好命令，能让你的开发效率翻倍！
 
---
 
> **课程反馈**：如果本教程对你有帮助，欢迎分享给更多人！
>
> **问题反馈**：遇到问题可以使用 `/bug` 命令报告，或在社区提问。
 
---