SDK 中的 slash commands
学习如何通过 SDK 使用 slash commands 来控制 Claude Code 会话
Slash commands 提供了一种方式来控制 Claude Code 会话，使用以 / 开头的特殊命令。这些命令可以通过 SDK 发送，以执行诸如压缩上下文、列出上下文使用情况或调用自定义命令等操作。只有在不需要交互式终端的情况下工作的命令才能通过 SDK 分派；system/init 消息列出了在您的会话中可用的命令。
发现可用的 Slash Commands
Claude Agent SDK 在系统初始化消息中提供有关可用 slash commands 的信息。在您的会话开始时访问此信息：
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Hello Claude",
options: { maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "init") {
console.log("Available slash commands:", message.slash_commands);
// Example output: ["/compact", "/context", "/usage"]
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage
async def main():
async for message in query(prompt="Hello Claude", options=ClaudeAgentOptions(max_turns=1)):
if isinstance(message, SystemMessage) and message.subtype == "init":
print("Available slash commands:", message.data["slash_commands"])
# Example output: ["/compact", "/context", "/usage"]
asyncio.run(main())
发送 Slash Commands
通过在您的提示字符串中包含 slash commands 来发送它们，就像常规文本一样：
import { query } from "@anthropic-ai/claude-agent-sdk";
// Send a slash command
for await (const message of query({
prompt: "/compact",
options: { maxTurns: 1 }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log("Command executed:", message.result);
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
async def main():
# Send a slash command
async for message in query(prompt="/compact", options=ClaudeAgentOptions(max_turns=1)):
if isinstance(message, ResultMessage):
print("Command executed:", message.result)
asyncio.run(main())
常见的 Slash Commands
/compact - 压缩对话历史
/compact 命令通过总结较早的消息同时保留重要上下文来减少您的对话历史的大小：
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "/compact",
options: { maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "compact_boundary") {
console.log("Compaction completed");
console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens);
console.log("Trigger:", message.compact_metadata.trigger);
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage
async def main():
async for message in query(prompt="/compact", options=ClaudeAgentOptions(max_turns=1)):
if isinstance(message, SystemMessage) and message.subtype == "compact_boundary":
print("Compaction completed")
print("Pre-compaction tokens:", message.data["compact_metadata"]["pre_tokens"])
print("Trigger:", message.data["compact_metadata"]["trigger"])
asyncio.run(main())
清除对话
交互式 /clear 命令在 SDK 中不可用。每个 query() 调用已经开始一个新的对话，所以要清除上下文，请结束当前的 query() 并开始一个新的。之前的对话保存在磁盘上，可以通过将其会话 ID 传递给 resume 选项 来返回。
创建自定义 Slash Commands
除了使用内置 slash commands 外，您还可以创建自己的自定义命令，这些命令可通过 SDK 使用。自定义命令定义为特定目录中的 markdown 文件，类似于 subagents 的配置方式。
文件位置
自定义 slash commands 根据其范围存储在指定的目录中：
- 项目命令：
.claude/commands/- 仅在当前项目中可用（旧版；优先使用.claude/skills/） - 个人命令：
~/.claude/commands/- 在您的所有项目中可用（旧版；优先使用~/.claude/skills/）
文件格式
每个自定义命令都是一个 markdown 文件，其中：
- 文件名（不带
.md扩展名）成为命令名称 - 文件内容定义命令的功能
- 可选的 YAML frontmatter 提供配置
基本示例
创建 .claude/commands/refactor.md：
Refactor the selected code to improve readability and maintainability.
Focus on clean code principles and best practices.
这创建了 /refactor 命令，您可以通过 SDK 使用它。
带有 Frontmatter
创建 .claude/commands/security-check.md：
---
allowed-tools: Read, Grep, Glob
description: Run security vulnerability scan
model: claude-opus-4-7
---
Analyze the codebase for security vulnerabilities including:
- SQL injection risks
- XSS vulnerabilities
- Exposed credentials
- Insecure configurations
在 SDK 中使用自定义命令
一旦在文件系统中定义，自定义命令就会自动通过 SDK 可用：
import { query } from "@anthropic-ai/claude-agent-sdk";
// Use a custom command
for await (const message of query({
prompt: "/refactor src/auth/login.ts",
options: { maxTurns: 3 }
})) {
if (message.type === "assistant") {
console.log("Refactoring suggestions:", message.message);
}
}
// Custom commands appear in the slash_commands list
for await (const message of query({
prompt: "Hello",
options: { maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "init") {
// Will include both built-in and custom commands
console.log("Available commands:", message.slash_commands);
// Example: ["/compact", "/context", "/usage", "/refactor", "/security-check"]
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, SystemMessage
async def main():
# Use a custom command
async for message in query(
prompt="/refactor src/auth/login.py", options=ClaudeAgentOptions(max_turns=3)
):
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print("Refactoring suggestions:", block.text)
# Custom commands appear in the slash_commands list
async for message in query(prompt="Hello", options=ClaudeAgentOptions(max_turns=1)):
if isinstance(message, SystemMessage) and message.subtype == "init":
# Will include both built-in and custom commands
print("Available commands:", message.data["slash_commands"])
# Example: ["/compact", "/context", "/usage", "/refactor", "/security-check"]
asyncio.run(main())
高级功能
参数和占位符
自定义命令支持使用占位符的动态参数：
创建 .claude/commands/fix-issue.md：
---
argument-hint: [issue-number] [priority]
description: Fix a GitHub issue
---
Fix issue #$1 with priority $2.
Check the issue description and implement the necessary changes.
在 SDK 中使用：
import { query } from "@anthropic-ai/claude-agent-sdk";
// Pass arguments to custom command
for await (const message of query({
prompt: "/fix-issue 123 high",
options: { maxTurns: 5 }
})) {
// Command will process with $1="123" and $2="high"
if (message.type === "result" && message.subtype === "success") {
console.log("Issue fixed:", message.result);
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
async def main():
# Pass arguments to custom command
async for message in query(prompt="/fix-issue 123 high", options=ClaudeAgentOptions(max_turns=5)):
# Command will process with $1="123" and $2="high"
if isinstance(message, ResultMessage):
print("Issue fixed:", message.result)
asyncio.run(main())
Bash 命令执行
自定义命令可以执行 bash 命令并包含其输出：
创建 .claude/commands/git-commit.md：
---
allowed-tools: Bash(git add *), Bash(git status *), Bash(git commit *)
description: Create a git commit
---
## Context
- Current status: !`git status`
- Current diff: !`git diff HEAD`
## Task
Create a git commit with appropriate message based on the changes.
文件引用
使用 @ 前缀包含文件内容：
创建 .claude/commands/review-config.md：
---
description: Review configuration files
---
Review the following configuration files for issues:
- Package config: @package.json
- TypeScript config: @tsconfig.json
- Environment config: @.env
Check for security issues, outdated dependencies, and misconfigurations.
使用命名空间进行组织
在子目录中组织命令以获得更好的结构：
.claude/commands/
├── frontend/
│ ├── component.md # Creates /component (project:frontend)
│ └── style-check.md # Creates /style-check (project:frontend)
├── backend/
│ ├── api-test.md # Creates /api-test (project:backend)
│ └── db-migrate.md # Creates /db-migrate (project:backend)
└── review.md # Creates /review (project)
子目录出现在命令描述中，但不影响命令名称本身。
实际示例
代码审查命令
创建 .claude/commands/code-review.md：
---
allowed-tools: Read, Grep, Glob, Bash(git diff *)
description: Comprehensive code review
---
## Changed Files
!`git diff --name-only HEAD~1`
## Detailed Changes
!`git diff HEAD~1`
## Review Checklist
Review the above changes for:
1. Code quality and readability
2. Security vulnerabilities
3. Performance implications
4. Test coverage
5. Documentation completeness
Provide specific, actionable feedback organized by priority.
测试运行器命令
创建 .claude/commands/test.md：
---
allowed-tools: Bash, Read, Edit
argument-hint: [test-pattern]
description: Run tests with optional pattern
---
Run tests matching pattern: $ARGUMENTS
1. Detect the test framework (Jest, pytest, etc.)
2. Run tests with the provided pattern
3. If tests fail, analyze and fix them
4. Re-run to verify fixes
通过 SDK 使用这些命令：
import { query } from "@anthropic-ai/claude-agent-sdk";
// Run code review
for await (const message of query({
prompt: "/code-review",
options: { maxTurns: 3 }
})) {
// Process review feedback
}
// Run specific tests
for await (const message of query({
prompt: "/test auth",
options: { maxTurns: 5 }
})) {
// Handle test results
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
# Run code review
async for message in query(prompt="/code-review", options=ClaudeAgentOptions(max_turns=3)):
# Process review feedback
pass
# Run specific tests
async for message in query(prompt="/test auth", options=ClaudeAgentOptions(max_turns=5)):
# Handle test results
pass
asyncio.run(main())
另请参阅
- Slash Commands - 完整的 slash command 文档
- SDK 中的 Subagents - 类似的基于文件系统的 subagents 配置
- TypeScript SDK 参考 - 完整的 API 文档
- SDK 概述 - 一般 SDK 概念
- CLI 参考 - 命令行界面