Skills 与自定义命令

Claude Code 里有两种容易混淆的复用机制：

Slash commands：你显式输入 /project:deploy、/user:daily 触发
Skills：Claude 根据描述按需加载，适合封装领域知识、脚本和资源

两者可以一起用，但不是同一个东西。

Slash commands

Slash command 本质是一段可复用提示词，适合明确、可命名、由用户主动触发的流程。

项目级命令

项目级命令放在 .claude/commands/：

.claude/commands/deploy.md

---
description: 运行项目发布前检查
argument-hint: [environment]
allowed-tools: Bash(pnpm test), Bash(pnpm build), Bash(git status)
---

请按顺序完成发布前检查：

1. 确认当前分支和未提交改动
2. 运行 pnpm test
3. 运行 pnpm build
4. 根据 $ARGUMENTS 判断目标环境
5. 汇总检查结果，不要自动发布

使用方式：

/project:deploy staging

个人全局命令

个人命令放在 ~/.claude/commands/：

~/.claude/commands/daily.md

使用方式：

/user:daily

全局命令适合个人习惯，不适合提交到团队仓库。

Skills

Skill 是一个带元数据的能力包，可以包含：

SKILL.md：入口说明和触发描述
scripts/：可执行脚本
references/：长文档、规范、模板
assets/：图片、样例、静态资源

典型结构：

.claude/
└── skills/
    └── api-generator/
        ├── SKILL.md
        ├── scripts/
        │   └── scaffold-api.ts
        └── references/
            └── api-style.md

SKILL.md 示例：

---
name: api-generator
description: 当用户要求创建 REST API、路由、控制器或接口测试时使用
---

你负责根据项目现有架构生成 API 代码。

工作规则：
1. 先读取现有路由、控制器、模型和测试
2. 优先复用项目已有 helper 和错误处理方式
3. 需要批量生成文件时，优先调用 scripts/scaffold-api.ts
4. 生成后运行相关测试，不要跳过类型检查

Claude 会根据 description 判断何时加载这个 Skill。description 要写触发场景，不要只写“很好用的 API 工具”。

怎么选

需求	选择
我想输入一个命令触发固定流程	Slash command
我想让 Claude 遇到某类任务自动加载规范	Skill
只是全项目通用约束	`CLAUDE.md`
需要确定性执行脚本	Hook 或 Skill 里的 script
需要连接外部工具	MCP

团队协作

可以提交到 Git 的内容：

.claude/commands/*.md
.claude/skills/*/SKILL.md
Skill 需要的脚本、模板、参考资料

不要提交：

个人 token
本机绝对路径
只适合一个人的 alias
自动发布、自动 push、自动删除资源的危险命令

一个稳妥的团队实践是：把高频工作流做成 slash command，把领域知识做成 Skill，把安全边界写进 settings.json 和 Hooks。