05COMMANDS & SKILLS
05 - 斜杠命令与 Skills
斜杠命令和 Skills 是两种不同的"能力入口"，用户层看起来都像 /xxx，但内部实现与生效方式差别很大。
读完你能回答
| 问题 |
|---|
/help 和 /init 虽然都是斜杠命令，处理方为什么不一样？ |
| Skill 是由模型触发还是用户触发？两者都可以吗？ |
| 想固化一段"复杂工作流"给以后复用，该用斜杠命令还是 Skill？ |
| 同名 Skill 出现在全局和项目里，哪个生效？ |
两种入口的路径差异
关键差异：客户端内置命令根本不经过模型；模型可见命令和 Skill 都会进入 Agent Loop，但加载的内容不同。
斜杠命令
斜杠命令是客户端层面的快捷入口，由 CLI 或 IDE 客户端直接解析。
| 类型 | 举例 | 处理方 | 模型感知 |
|---|---|---|---|
| 客户端内置 | /help /clear /model /login /logout |
客户端本地执行 | 否 |
| 模型可见 | /init /review 等 |
展开为 prompt 发给模型 | 是（像用户说了那句话） |
| 外部插件 | 用户自定义 | 客户端分发 | 视实现 |
客户端内置命令（代表）
| 命令 | 作用 |
|---|---|
/help |
打开帮助 |
/clear |
清空当前会话上下文 |
/model |
切换当前使用的模型 |
/login /logout |
账号登录态管理 |
/config |
打开配置面板 |
这类命令不消耗 token，执行过程模型看不到。
模型可见命令
这类命令被客户端展开为一段预定义提示词插入 user 消息，再进入正常的 Agent Loop。对模型而言和普通用户输入没有本质区别，只是内容是结构化的。
展开 /init 的展开路径
用户输入 /init，客户端内部大致等价于：
<user turn 被替换成>
请阅读当前仓库的结构和关键文件，生成一份 CLAUDE.md，
其中包含：主要目录作用、技术栈、测试约定、代码风格、分支规范。
将生成的内容直接写入项目根的 CLAUDE.md。模型收到这段 prompt，进入 Agent Loop，调用 Read / Glob / Grep 扫描仓库，最后用 Write 生成 CLAUDE.md。从用户视角看是"跑了一个命令"，从模型视角看是"收到一段长指令"。
Skills
Skill 是一段可按名调用的工作流说明。它解决的问题是：某类任务有固定套路，与其每次让模型现想，不如把套路存下来，需要时由模型按需加载并执行。
定义
一个 Skill 是一个目录，最少包含一个 SKILL.md。
| 文件 | 内容 |
|---|---|
SKILL.md |
说明文档，frontmatter 决定是否被触发，正文是工作指令 |
| 可选辅助脚本 | Shell / Python 脚本，由 Skill 执行时调用 |
| 可选资源文件 | 模板、配置、参考数据 |
展开一个最小可跑的 SKILL.md
---
name: update-changelog
description: Update CHANGELOG.md with the latest diff. Use after shipping a feature.
---
# Update Changelog
1. Read the current CHANGELOG.md
2. Run `git log main..HEAD --oneline` to see what changed since last release
3. Group commits into Added / Changed / Fixed sections
4. Insert a new entry at the top with today's date
5. Write the file back
Keep entries concise — one line per change, user-facing language.关键点：
frontmatter里的description必须写清楚"什么时候用"，因为这一行会进入系统提示词的 Skills 清单，模型就靠它判断该不该触发- 正文是写给模型的"工作手册"，用命令式，步骤清晰
- 目录里可以放辅助资产：
scripts/check-format.sh、reference/style-guide.md等，在 SKILL.md 里引用
目录结构：
.claude/skills/update-changelog/
├── SKILL.md ← 必需
├── scripts/
│ └── group-commits.sh ← 可选辅助
└── reference/
└── voice-examples.md ← 可选参考存放位置与优先级
| 路径 | 作用范围 | 优先级 |
|---|---|---|
~/.claude/skills/<name>/ |
用户级，跨项目可用 | 低 |
<repo>/.claude/skills/<name>/ |
项目级，仅该仓库会话中可见 | 高 |
同名 Skill 以项目级优先。这和 CLAUDE.md 的合并规则是一致的——越"具体"的越先生效。
调用路径
两种触发方式的区别：
- 用户直接触发（
/skill-name）：客户端把它转成 Skill 工具调用 - 模型自主触发：模型根据 Skills 清单里的
description判断该用哪个 Skill
两者的边界
| 维度 | 斜杠命令 | Skill |
|---|---|---|
| 调用方式 | 客户端识别 | 模型识别并决定调用 |
| 生效范围 | 客户端范围内 | 会话范围内 |
| 内容位置 | 客户端代码里（固化） | 文件系统里可编辑 |
| 谁可以自定义 | 客户端作者 | 用户 |
| 更新方式 | 升级客户端 | 改 SKILL.md 立即生效 |
选哪个？
| 你想做什么 | 选 |
|---|---|
| 快捷键式的客户端操作（切换模型、清屏） | 斜杠命令（但你只能用已有的，无法自己加） |
| 可复用的工作流（审 PR、生 changelog、做迁移） | Skill |
| 跨项目通用的规则 | 全局 Skill + ~/.claude/CLAUDE.md |
| 项目特定的流程 | 项目 Skill + <repo>/CLAUDE.md |
斜杠命令固化在客户端，你改不了；Skill 由用户自己维护。想要"自定义一个可复用的套路"，答案永远是 Skill。