Claude Code 斜杠命令怎么写：.claude/commands 与 Skills
Claude Code 里反复粘贴同一段审查清单，就写成斜杠命令：会话里敲 /review-diff 就跑。官方已把「自定义命令」并进 Skills——.claude/commands/*.md 仍可用，新工作更推荐 .claude/skills/<名>/SKILL.md。下面按官方 Skills 文档整理写法，并在本机用 Claude Code 2.1.309（2026-10-29，北京时间）搭可丢弃 demo，核对文件布局、校验与加载日志。
环境：Debian box；claude --version → 2.1.309 (Claude Code)；演示目录 /workspace/proj-test/cc-slash-demo。本机创建了 2 个 command 文件与 1 个 skill，跑过 claude plugin validate，并用 claude --debug -p … 核对加载计数。
先分清：内置命令、捆绑 Skill、你自己的斜杠命令
会话里敲 / 会出现一长串名字，来源不同：
- 内置命令：如
/help、/compact，走固定逻辑。 - 捆绑 Skill：如
/doctor、/code-review，官方写好的提示词流程；可用设置关掉。 - 你写的命令 / Skill：仓库或用户目录里的 Markdown，按文件名变成
/名字。
官方写明：自定义命令已并入 Skills。.claude/commands/deploy.md 与 .claude/skills/deploy/SKILL.md 都会生成 /deploy，行为一致。旧文件还能用；新工作优先 Skill：可带辅助文件，能控制「你敲还是模型自己调用」，相关对话里也能自动加载。
plugin validate 对 commands / skills 均 ✔；debug 记 Loaded 3 unique skills (... project: 1, ... legacy commands: 2)。落盘位置：项目共享还是只给自己
| 放哪 | 路径 | 谁能用 |
|---|---|---|
| 项目命令（旧式） | .claude/commands/*.md | 进 git，团队共享 |
| 项目 Skill（推荐） | .claude/skills/<名>/SKILL.md | 进 git；可带 scripts / 参考文件 |
| 个人命令 / Skill | ~/.claude/commands/ 或 ~/.claude/skills/ | 仅本机、跨项目 |
| 子目录命名 | commands/frontend/component.md | 调用名变成 /frontend:component |
同名时官方顺序是：企业托管 > 个人 > 项目；Skill 目录盖过同名的 .claude/commands/ 文件。插件 Skill 带命名空间（/插件名:技能名），很少和本地短名撞车。
写第一个命令：三分钟可复制
在仓库里建 demo 文件（文件名即命令名）：
mkdir -p .claude/commands .claude/commands/frontend .claude/skills/status-report
# 1) 旧式单文件命令 → /review-diff
cat > .claude/commands/review-diff.md <<'EOF'
---
description: Summarize uncommitted git diff and flag risks
disable-model-invocation: true
argument-hint: "[path]"
---
Summarize the uncommitted changes$ARGUMENTS for this repo in 3 bullets.
Flag missing tests, hardcoded secrets, and renames that break imports.
If the working tree is clean, say so and stop.
EOF
# 2) 子目录命名 → /frontend:component
cat > .claude/commands/frontend/component.md <<'EOF'
---
description: Scaffold a small React component checklist
disable-model-invocation: true
---
Create a checklist for a new frontend component named $ARGUMENTS:
1. File location under src/components/
2. Props type
3. Accessibility notes
4. One unit-test stub
EOF
frontmatter 里几条最常用：
description：给模型判断「该不该自动调用」；只想手动敲时，再加disable-model-invocation: true。$ARGUMENTS/$0：调用时跟在命令后的参数；argument-hint只影响补全提示。allowed-tools：该轮临时放行工具（下一条用户消息后失效）。
新工作改用 Skill 目录时，把同样内容放进 SKILL.md，并可写 !`git status -sb` 这类动态注入——命令输出在送进模型前会替换进正文：
---
name: status-report
description: Write a short project status report from git log and status.
disable-model-invocation: true
allowed-tools: Bash(git *)
---
## Repo snapshot
!`git status -sb`
## Recent commits
!`git log -5 --oneline`
## Your task
Write a 5-line status report for stakeholders from the snapshot above.
!`git …` 做动态上下文注入。流程写进
/名字，别继续往 CLAUDE.md 里堆——命令按需加载；记忆文件每次开局都占配额。
本机怎么验收：validate + debug 计数
在 /workspace/proj-test/cc-slash-demo 里，本机跑了这些（2026-10-29）：
claude plugin validate .claude/commands # ✔ Validation passed
claude plugin validate .claude/skills # ✔ Validation passed
claude --debug -p '…' # 看加载日志
debug 日志里有两行关键（时间已换算到北京时间 09:06）：
Loading skills from: … project=[…/cc-slash-demo/.claude/skills]Loaded 3 unique skills (... project: 1, ... legacy commands: 2)
也就是：1 个项目 Skill（status-report）+ 2 个旧式 command（review-diff、frontend/component）。同一次启动还会监视 .claude/skills 与 .claude/commands，改文件后一般不必重启会话。CLI 另有 --disable-slash-commands，会关掉 skills 与 commands（内置能力另说）。
已登录的会话里，官方验收方式是敲 / 看菜单，或跑 /skills；直接输入 /review-diff、/frontend:component、/status-report 调用。加载计数与校验不依赖模型调用；交互菜单与真实回复则要在已登录会话里点。
命令 vs Skill：一张对照表
| 维度 | .claude/commands/*.md | .claude/skills/<名>/SKILL.md |
|---|---|---|
| 命令名来源 | 文件名（含子目录 :） | 目录名或 frontmatter name |
| 辅助文件 | 单文件为主 | 同目录可放 scripts / 参考 md |
动态注入 !`cmd` | 支持 | 支持 |
| 官方态度 | 兼容旧格式 | 新工作首选 |
| 本机 demo | 2 个文件，debug 计为 legacy commands: 2 | 1 个目录，debug 计为 project: 1 |
参数、动态注入与「谁来触发」
斜杠命令适合反复跑的同一套步骤。参数用 $ARGUMENTS（整段）或 $0/$1（按位）写进正文；多词参数要加引号，例如 /frontend:component "SearchBar"。Skill 还可以声明 arguments: [issue, branch]，正文里用 $issue 这类具名占位。
动态注入 !`shell` 在渲染命令时先跑，再把输出塞进提示。适合 git diff、gh pr view 这类必须读当前工作区的上下文。注入命令失败会整次调用中止；需要允许非零退出时可按文档在命令后加 || true。组织若打开 disableSkillShellExecution，注入会被占位符替换，不会在本机执行。
触发权两字段记清：
disable-model-invocation: true——只有你敲/名字才会跑；适合部署、发 Slack、改生产配置。user-invocable: false——菜单里隐藏，只给模型当背景知识自动加载；适合「遗留系统说明」这类不宜当按钮的材料。
默认两者都不写：你能敲，模型也能在描述匹配时自己加载。描述写短、把触发词放前面——官方会把 description 与 when_to_use 合计截到约 1536 字符。
和 CLAUDE.md、Hooks 怎么分工
三样东西分开放：
- CLAUDE.md：每会话都要用的事实（构建命令、目录约定、Always/Never）。开局就进上下文，宜短。
- 斜杠命令 / Skill：按需加载的多步流程。审查 PR、出状态报告、生成组件清单——写进
/名字。 - permissions / Hooks：硬边界。禁止删
.env、拦危险 Bash，靠 allow/deny 或 Hook，不靠命令正文里的「请不要」。
官方 Skills 文档也提醒：一段 CLAUDE.md 如果长成了操作流程，就迁到 Skill，让正文只在调用时加载。站内CLAUDE.md 怎么写与grill-me 是同一套思路的两侧。
常见坑
- 写了菜单里没有：核对路径是不是
.claude/commands/或.claude/skills/<名>/SKILL.md；名字含零宽字符 /<会被拒绝。改完可看 debug，或跑/reload-skills。 - 同名被盖住：个人目录的同名 Skill 会盖过项目；插件则带前缀。先
/skills看实际来源。 - 参数没进去：正文要写
$ARGUMENTS或$0；一个占位都没有时，CLI 会把参数附在末尾ARGUMENTS: …。 - 只想手动触发却被自动跑：加
disable-model-invocation: true（适合/deploy、/commit这类有副作用的流程）。 - 和 CLAUDE.md 抢配额：多步流程放斜杠命令 / Skill；CLAUDE.md 只留每会话都要用的事实（见CLAUDE.md 怎么写）。
本机 demo 目录已 git init，方便以后在已登录会话里直接试带 !`git …` 的 Skill；命令文件本身不依赖 git 也能被加载与校验；把 demo 放进版本库只是为了以后复用同一套命令，也方便同事直接拉下来试。
完成标准
- 仓库里至少有一个
.claude/commands/<名>.md或.claude/skills/<名>/SKILL.md。 claude plugin validate对该目录显示 Validation passed。claude --debug -p …的日志里能看到对应的 project / legacy commands 计数。- 已登录会话中，
/菜单或直接/名字能点到这条命令。
最后
先写一条高频流程到 .claude/commands/某名.md，validate 通过后再迁到 Skill 目录加脚本。要硬拦危险动作，靠权限与Hooks，别只写在斜杠命令正文里。
