Slash Commands no SDK
Aprenda como usar slash commands para controlar sessões do Claude Code através do SDK
Slash commands fornecem uma maneira de controlar sessões do Claude Code com comandos especiais que começam com /. Esses comandos podem ser enviados através do SDK para executar ações como compactar contexto, listar uso de contexto ou invocar comandos personalizados. Apenas comandos que funcionam sem um terminal interativo são despachados através do SDK; a mensagem system/init lista os disponíveis em sua sessão.
Descobrindo Slash Commands Disponíveis
O Claude Agent SDK fornece informações sobre slash commands disponíveis na mensagem de inicialização do sistema. Acesse essas informações quando sua sessão começar:
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())
Enviando Slash Commands
Envie slash commands incluindo-os em sua string de prompt, assim como texto regular:
import { query } from "@anthropic-ai/claude-agent-sdk";
// Enviar um 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():
# Enviar um 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 Comuns
/compact - Compactar Histórico de Conversa
O comando /compact reduz o tamanho do seu histórico de conversa resumindo mensagens antigas enquanto preserva contexto importante:
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())
Limpando a conversa
O comando interativo /clear não está disponível no SDK. Cada chamada query() já inicia uma conversa nova, então para limpar contexto, termine a query() atual e inicie uma nova. A conversa anterior fica no disco e pode ser retomada passando seu ID de sessão para a opção resume.
Criando Slash Commands Personalizados
Além de usar slash commands integrados, você pode criar seus próprios comandos personalizados que estão disponíveis através do SDK. Comandos personalizados são definidos como arquivos markdown em diretórios específicos, similar a como subagentes são configurados.
Localizações de Arquivo
Slash commands personalizados são armazenados em diretórios designados baseado em seu escopo:
- Comandos de projeto:
.claude/commands/- Disponíveis apenas no projeto atual (legado; prefira.claude/skills/) - Comandos pessoais:
~/.claude/commands/- Disponíveis em todos seus projetos (legado; prefira~/.claude/skills/)
Formato de Arquivo
Cada comando personalizado é um arquivo markdown onde:
- O nome do arquivo (sem extensão
.md) se torna o nome do comando - O conteúdo do arquivo define o que o comando faz
- Frontmatter YAML opcional fornece configuração
Exemplo Básico
Crie .claude/commands/refactor.md:
Refactor the selected code to improve readability and maintainability.
Focus on clean code principles and best practices.
Isso cria o comando /refactor que você pode usar através do SDK.
Com Frontmatter
Crie .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
Usando Slash Commands Personalizados no SDK
Uma vez definidos no sistema de arquivos, comandos personalizados estão automaticamente disponíveis através do 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())
Recursos Avançados
Argumentos e Placeholders
Comandos personalizados suportam argumentos dinâmicos usando placeholders:
Crie .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.
Use no 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())
Execução de Comando Bash
Comandos personalizados podem executar comandos bash e incluir sua saída:
Crie .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.
Referências de Arquivo
Inclua conteúdos de arquivo usando o prefixo @:
Crie .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.
Organização com Namespacing
Organize comandos em subdiretórios para melhor estrutura:
.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)
O subdiretório aparece na descrição do comando mas não afeta o nome do comando em si.
Exemplos Práticos
Comando de Revisão de Código
Crie .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.
Comando Test Runner
Crie .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
Use esses comandos através do 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())
Veja Também
- Slash Commands - Documentação completa de slash commands
- Subagentes no SDK - Configuração similar baseada em sistema de arquivos para subagentes
- Referência TypeScript SDK - Documentação completa da API
- Visão geral do SDK - Conceitos gerais do SDK
- Referência CLI - Interface de linha de comando