Claude Code Skills 与 Slash Commands 新版指南：自定义命令已并入 Skills

Claude Code 的自定义命令体系已经发生变化：Custom commands 已并入 Skills。过去你可能在 .claude/commands/deploy.md 写 /deploy，现在推荐使用 .claude/skills/deploy/SKILL.md。旧 commands 仍可用，但 Skills 更强。

一句话理解 Skills#

Skill 是一个可复用的工作流包：

my-skill/
├── SKILL.md
├── template.md
├── examples/
│   └── sample.md
└── scripts/
    └── validate.sh

SKILL.md 是入口，包含：

• YAML frontmatter：告诉 Claude 什么时候使用
• Markdown body：具体执行步骤和规则

你可以直接输入：

/skill-name

也可以让 Claude 根据 description 自动决定是否调用。

Commands 与 Skills 的关系#

官方说明：

• .claude/commands/deploy.md 可以创建 /deploy
• .claude/skills/deploy/SKILL.md 也可以创建 /deploy
• 两者同时存在时，Skill 优先
• Commands 继续兼容，但 Skills 推荐使用

Skills 的额外优势：

1. 可以带 supporting files
2. 可以用 frontmatter 控制是否允许自动调用
3. 可以在 Subagent / fork context 中运行
4. 支持动态上下文注入
5. 遵循 Agent Skills 开放标准

创建第一个 Skill#

mkdir -p ~/.claude/skills/summarize-changes

~/.claude/skills/summarize-changes/SKILL.md：

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

这里的关键是：

!`git diff HEAD`

这是动态上下文注入。Claude Code 会先运行命令，把输出替换进 Skill，再让 Claude 读取。这样 Skill 不是凭空猜测，而是基于实时 diff。

Skill 存储位置与优先级#

同名冲突优先级：

Enterprise > Personal > Project

Plugin Skill 使用命名空间，例如：

/plugin-name:skill-name

所以不会和普通 Skill 冲突。

Live Change Detection#

Claude Code 会监听 Skill 目录变更。你新增、编辑或删除：

• ~/.claude/skills/
• 项目 .claude/skills/
• --add-dir 里的 .claude/skills/

当前 session 通常会自动生效，不需要重启。

但如果 session 启动时顶层 skills 目录不存在，新建顶层目录后需要重启 Claude Code 才能被 watch。

Monorepo 自动发现#

Claude Code 会从启动目录向上到 repo root 发现 .claude/skills/。

当你编辑子目录里的文件时，也会按需发现嵌套 skills：

repo/
├── .claude/skills/release/SKILL.md
└── packages/
    └── frontend/
        └── .claude/skills/react-component/SKILL.md

如果你在 packages/frontend/ 工作，Claude Code 会发现 frontend 专属 Skill。

Task Skill vs Reference Skill#

Reference content#

适合项目约定、代码风格、领域知识：

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

这类 Skill 可能由 Claude 自动加载。

Task content#

适合部署、提交、生成代码等步骤化任务：

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

disable-model-invocation: true 表示只允许用户手动调用，Claude 不能自动触发。适合部署、发布、删除等敏感流程。

什么时候从 CLAUDE.md 拆成 Skill？#

如果 CLAUDE.md 里出现这类内容，就该拆成 Skill：

• 多步骤流程
• 很长的 checklist
• 只在特定任务时需要的参考材料
• 模板和示例输出
• 需要运行脚本的流程

保留在 CLAUDE.md 的应该是：

• 持续有效的项目事实
• 常用命令
• 不应修改的目录
• 代码风格的核心原则

推荐 Skill 模板：安全审查#

---
name: security-review
description: Review current changes for security risks. Use before opening a PR or when user asks for security review.
context: fork
---

## Current diff

!`git diff HEAD`

## Review checklist

Check for:
1. SQL injection
2. XSS
3. Missing authorization
4. Secrets in code or logs
5. Unsafe deserialization
6. SSRF
7. Path traversal

## Output format

Group findings by severity:
- Critical
- Warning
- Suggestion

For each finding include file path, risk, and fix.

最佳实践#

1. Skill body 保持精简；长材料放 supporting files
2. Task 型 Skill 默认考虑 disable-model-invocation: true
3. 会污染上下文或需要隔离的任务用 context: fork
4. 用动态上下文注入把实时 diff、日志、配置带进来
5. 项目共享 Skill 放 .claude/skills/ 并提交到 Git
6. 个人 Skill 放 ~/.claude/skills/
7. 不再新增 .claude/commands/，新内容优先用 Skills

来源：Claude Code 官方文档 - Extend Claude with skills | 整理：ClaudeEagle