Claude Code Custom Slash Commands

Skills are the extension mechanism for Claude Code, through custom slash commands (e.g.,/deploy、/explain-code) to enhance Claude's capabilities.

Each custom command is essentially an independent Skill file that can encapsulate complex workflows, project conventions, and common operations, allowing you to invoke it quickly in any session.

Custom commands have been integrated into the Skills system — located at.claude/commands/deploy.mdthe command files and located at.claude/skills/deploy/SKILL.mdthe Skill files will all create/deploycommands, working in the same way.

In essence,.claude/commands/is the shorthand form of Skills, and the two directory structures are completely equivalent.

Why Use Custom Slash Commands

The core value of custom slash commands lies inStandardization + Reuse：

• Codify Workflows: Encapsulate common multi-step operations (such as "deploy to production") into a single command
• Ensure team consistency: Codify project conventions (such as "code review checklist") into commands to ensure team members follow the same standards
• Reduce cognitive load: No need to memorize complex command combinations; a single sentence can trigger the complete workflow
• Reduce repetitive input: High-frequency tasks change from multi-step operations to a single invocation

The experience of Anthropic's internal team is: tasks performed more than twice a day should be turned into Skills. Get it right once, and it keeps working.

File Structure

Each Skill is a directory that contains a requiredSKILL.mdfile:

my-skill/
├── SKILL.md           # 主指令文件（必需）
├── template.md        # Claude 填充的模板
├── examples/
│   └── sample.md      # 展示预期格式的示例
└── scripts/
    └── validate.sh    # Claude 可以执行的脚本

The file format consists of two parts:

• YAML frontmatter(located---between the delimiters): used to configure metadata
• Markdown body: the instructions Claude follows when invoked

Create Your First Custom Slash Command

1. Create a Skill Directory

Create the skill directory in an appropriate location. The storage location determines the command's scope:

mkdir -p ~/.claude/skills/explain-code
# 或者在项目中创建
mkdir -p .claude/skills/explain-code

2. Write the SKILL.md File

In the directory, createSKILL.md, containing YAML frontmatter and instructions:

3. Use the Custom Command

Directly invoke it in Claude Code:

/explain-code src/auth/login.ts

Claude will automatically match a skill that fits the description, or you can invoke it explicitly.

Configuration Fields Explained

Invocation Control

Control who can invoke the skill via frontmatter:

Variable Substitution

Use variables in the skill content, and Claude will replace them automatically:

Skill Storage Locations

Skills can be stored in multiple locations with different scopes:

.claude/commands/Files within them are still valid, supporting the same frontmatter. If a skill and a command share the same name, the skill takes precedence.

Advanced Examples

Example 1: Deployment Command (Manual Invocation Only)

Example 2: Component Migration Command with Arguments

Example 3: PR Summary Command with Dynamic Context

Built-in Slash Commands

Claude Code provides some built-in commands that work out of the box:

Best Practices

1. How to Write description

The description is the basis for Claude's auto-invocation, so be sure to write it clearly:

• Clarify trigger timing:Call when the user requests review / analysis / inspection of code quality
• State preconditions:Use after the specification document has been confirmed
• Write clear boundaries: cases in which it should not be invoked

2. Single Responsibility Principle

Each skill should do only one thing, with clear inputs/outputs:

• /deploy: only responsible for deployment
• /test: only responsible for running tests
• /review: only responsible for code review

3. Set Invocation Permissions as Needed

• Dangerous operations (deploy, delete): Settingsdisable-model-invocation: true
• Claude auxiliary tasks: Settingsuser-invocable: false
• General workflow: use default configuration

4. Use allowed-tools to Restrict Permissions

Set minimal permissions for security-critical operations:

Team Sharing Strategy

Commit project-level skills to git for team sharing:

my-project/
├── .claude/
│   ├── skills/
│   │   ├── deploy/
│   │   │   └── SKILL.md
│   │   ├── test/
│   │   │   └── SKILL.md
│   │   └── review/
│   │       └── SKILL.md
│   └── commands/  # 也可以用 commands/ 目录
└── CLAUDE.md

Reference and explain project-specific skills in CLAUDE.md:

## 自定义斜杠命令

本项目提供以下自定义斜杠命令：

- `/deploy [env]` — 部署到指定环境（dev/staging/prod）
- `/test [module]` — 运行测试套件或指定模块
- `/review` — 执行标准代码审查

详细使用说明请参考 @.claude/skills/README.md

FAQ

Q: What is the difference between skills and the commands directory?

Essentially no difference..claude/commands/Yes.claude/skills/shorthand form, both formats work fine. If they share the same name, skills take priority.

Q: How do I pass multiple parameters when calling?

Use quotes to wrap multiple parameters:/migrate SearchBar "from:React to:Vue", then use it in the skill$ARGUMENTSto get the complete string.

Q: Can skills be used in sub-agents?

Yes. By setting thecontext: forkandagentfield, sub-agents can run skills in an independent context.

Q: How do I make Claude remember commonly used skills?

List all available custom commands and their usage scenarios in CLAUDE.md, and Claude will automatically match the appropriate skill based on the descriptions.