artubss/SKILLS-CLAUDE-CODE / skills/skills/development/command-development
Command Development
UnverifiedEsta habilidade deve ser usada quando o usuário pede para "criar um slash command", "adicionar um comando", "escrever um comando personalizado", "definir argumentos de comando", "usar frontmatter de comando", "organizar comandos", "criar comando com referências de arquivo", "comando interativo", "usar AskUserQuestion em comando", ou precisa de orientação sobre estrutura de slash command, campos de frontmatter YAML, argumentos dinâmicos, execução bash em comandos, padrões de interação com usuário, ou melhores práticas de desenvolvimento de comando para Claude Code.
Command Development para Claude Code
Visão geral
Slash commands são prompts frequentemente usados definidos como arquivos Markdown que Claude executa durante sessões interativas. Compreender estrutura de comando, opções de frontmatter e recursos dinâmicos permite criar workflows poderosos e reutilizáveis.
Conceitos-chave:
- Formato de arquivo Markdown para comandos
- Frontmatter YAML para configuração
- Argumentos dinâmicos e referências de arquivo
- Execução bash para contexto
- Organização e namespacing de comandos
Fundamentos de Command
O que é um Slash Command?
Um slash command é um arquivo Markdown contendo um prompt que Claude executa quando invocado. Comandos fornecem:
- Reutilização: Define uma vez, usa repetidamente
- Consistência: Padroniza workflows comuns
- Compartilhamento: Distribui entre equipe ou projetos
- Eficiência: Acesso rápido a prompts complexos
Crítico: Commands são Instruções PARA Claude
Commands são escritas para consumo do agent, não consumo humano.
Quando um usuário invoca /command-name, o conteúdo do comando se torna as instruções do Claude. Escreva comandos como diretivas PARA Claude sobre o que fazer, não como mensagens PARA o usuário.
Abordagem correta (instruções para Claude):
Revise este código em busca de vulnerabilidades de segurança incluindo:
- SQL injection
- XSS attacks
- Problemas de autenticação
Forneça números de linha específicos e classificações de severidade.
Abordagem incorreta (mensagens para usuário):
Este comando revisará seu código em busca de problemas de segurança.
Você receberá um relatório com detalhes de vulnerabilidades.
O primeiro exemplo instrui Claude sobre o que fazer. O segundo diz ao usuário o que acontecerá mas não instrui Claude. Sempre use a primeira abordagem.
Locais de Command
Project commands (compartilhados com equipe):
- Localização:
.claude/commands/ - Escopo: Disponível em projeto específico
- Label: Mostrado como "(project)" em
/help - Use para: Workflows de equipe, tarefas específicas do projeto
Personal commands (disponíveis em todo lugar):
- Localização:
~/.claude/commands/ - Escopo: Disponível em todos os projetos
- Label: Mostrado como "(user)" em
/help - Use para: Workflows pessoais, utilitários entre projetos
Plugin commands (agrupados com plugins):
- Localização:
plugin-name/commands/ - Escopo: Disponível quando plugin instalado
- Label: Mostrado como "(plugin-name)" em
/help - Use para: Funcionalidade específica do plugin
Formato de Arquivo
Estrutura Básica
Commands são arquivos Markdown com extensão .md:
.claude/commands/
├── review.md # /review command
├── test.md # /test command
└── deploy.md # /deploy command
Comando simples:
Revise este código em busca de vulnerabilidades de segurança incluindo:
- SQL injection
- XSS attacks
- Bypass de autenticação
- Tratamento inseguro de dados
Nenhum frontmatter necessário para comandos básicos.
Com YAML Frontmatter
Adicione configuração usando YAML frontmatter:
---
description: Revise código em busca de problemas de segurança
allowed-tools: Read, Grep, Bash(git:*)
model: sonnet
---
Revise este código em busca de vulnerabilidades de segurança...
Campos YAML Frontmatter
description
Propósito: Descrição breve mostrada em /help
Tipo: String
Padrão: Primeira linha do prompt do comando
---
description: Revise pull request em busca de qualidade de código
---
Melhores práticas: Descrição clara e acionável (menos de 60 caracteres)
allowed-tools
Propósito: Especifique quais ferramentas o comando pode usar Tipo: String ou Array Padrão: Herda da conversa
---
allowed-tools: Read, Write, Edit, Bash(git:*)
---
Padrões:
Read, Write, Edit- Ferramentas específicasBash(git:*)- Bash apenas com comandos git*- Todas as ferramentas (raramente necessário)
Use quando: Comando requer acesso a ferramentas específicas
model
Propósito: Especifique modelo para execução do comando Tipo: String (sonnet, opus, haiku) Padrão: Herda da conversa
---
model: haiku
---
Casos de uso:
haiku- Comandos rápidos e simplessonnet- Workflows padrãoopus- Análise complexa
argument-hint
Propósito: Documente argumentos esperados para autocomplete Tipo: String Padrão: Nenhum
---
argument-hint: [pr-number] [priority] [assignee]
---
Benefícios:
- Ajuda usuários a entender argumentos do comando
- Melhora descoberta de comando
- Documenta interface do comando
disable-model-invocation
Propósito: Impeça a ferramenta SlashCommand de chamar comando programaticamente Tipo: Boolean Padrão: false
---
disable-model-invocation: true
---
Use quando: Comando deve ser apenas invocado manualmente
Argumentos Dinâmicos
Usando $ARGUMENTS
Capture todos os argumentos como string única:
---
description: Corrija problema por número
argument-hint: [issue-number]
---
Corrija o problema #$ARGUMENTS seguindo nossos padrões de codificação e melhores práticas.
Uso:
> /fix-issue 123
> /fix-issue 456
Expande para:
Corrija o problema #123 seguindo nossos padrões de codificação...
Corrija o problema #456 seguindo nossos padrões de codificação...
Usando Argumentos Posicionais
Capture argumentos individuais com $1, $2, $3, etc.:
---
description: Revise PR com prioridade e responsável
argument-hint: [pr-number] [priority] [assignee]
---
Revise pull request #$1 com nível de prioridade $2.
Após revisão, atribua a $3 para acompanhamento.
Uso:
> /review-pr 123 high alice
Expande para:
Revise pull request #123 com nível de prioridade high.
Após revisão, atribua a alice para acompanhamento.
Combinando Argumentos
Misture argumentos posicionais e restantes:
Deploy $1 para ambiente $2 com opções: $3
Uso:
> /deploy api staging --force --skip-tests
Expande para:
Deploy api para ambiente staging com opções: --force --skip-tests
Referências de Arquivo
Usando Sintaxe @
Inclua conteúdo de arquivo em comando:
---
description: Revise arquivo específico
argument-hint: [file-path]
---
Revise @$1 em busca de:
- Qualidade de código
- Melhores práticas
- Bugs potenciais
Uso:
> /review-file src/api/users.ts
Efeito: Claude lê src/api/users.ts antes de processar comando
Múltiplas Referências de Arquivo
Referencie múltiplos arquivos:
Compare @src/old-version.js com @src/new-version.js
Identifique:
- Mudanças breaking
- Novos recursos
- Correções de bugs
Referências de Arquivo Estáticas
Referencie arquivos conhecidos sem argumentos:
Revise @package.json e @tsconfig.json em busca de consistência
Garanta:
- Versão TypeScript corresponde
- Dependências estão alinhadas
- Configuração de build está correta
Execução Bash em Commands
Commands podem executar comandos bash inline para dinamicamente reunir contexto antes de Claude processar o comando. Isso é útil para incluir estado do repositório, informações de ambiente, ou contexto específico do projeto.
Quando usar:
- Inclua contexto dinâmico (git status, variáveis de ambiente, etc.)
- Reúna estado do projeto/repositório
- Construa workflows ciente de contexto
Detalhes de implementação:
Para sintaxe completa, exemplos e melhores práticas, veja seção references/plugin-features-reference.md sobre execução bash. A referência inclui a sintaxe exata e múltiplos exemplos funcionais para evitar problemas de execução
Organização de Command
Estrutura Plana
Organização simples para pequenos conjuntos de comando:
.claude/commands/
├── build.md
├── test.md
├── deploy.md
├── review.md
└── docs.md
Use quando: 5-15 comandos, sem categorias claras
Estrutura com Namespacing
Organize commands em subdiretórios:
.claude/commands/
├── ci/
│ ├── build.md # /build (project:ci)
│ ├── test.md # /test (project:ci)
│ └── lint.md # /lint (project:ci)
├── git/
│ ├── commit.md # /commit (project:git)
│ └── pr.md # /pr (project:git)
└── docs/
├── generate.md # /generate (project:docs)
└── publish.md # /publish (project:docs)
Benefícios:
- Agrupamento lógico por categoria
- Namespace mostrado em
/help - Mais fácil encontrar comandos relacionados
Use quando: 15+ comandos, categorias claras
Melhores Práticas
Design de Command
- Responsabilidade única: Um comando, uma tarefa
- Descrições claras: Auto-explicativas em
/help - Dependências explícitas: Use
allowed-toolsquando necessário - Documente argumentos: Sempre forneça
argument-hint - Nomenclatura consistente: Use padrão verbo-substantivo (review-pr, fix-issue)
Manipulação de Argumentos
- Valide argumentos: Verifique argumentos obrigatórios no prompt
- Forneça padrões: Sugira padrões quando argumentos faltam
- Documente formato: Explique formato de argumento esperado
- Lide com casos extremos: Considere argumentos faltantes ou inválidos
---
argument-hint: [pr-number]
---
$IF($1,
Revise PR #$1,
Forneça um número de PR. Uso: /review-pr [number]
)
Referências de Arquivo
- Caminhos explícitos: Use caminhos de arquivo claros
- Verifique existência: Lide com arquivos ausentes graciosamente
- Caminhos relativos: Use caminhos relativos ao projeto
- Suporte Glob: Considere usar ferramenta Glob para padrões
Comandos Bash
- Limite escopo: Use
Bash(git:*)nãoBash(*) - Comandos seguros: Evite operações destrutivas
- Lide com erros: Considere falhas de comando
- Mantenha rápido: Comandos de longa execução retardam invocação
Documentação
- Adicione comentários: Explique lógica complexa
- Forneça exemplos: Mostre uso em comentários
- Liste requisitos: Documente dependências
- Versione comandos: Anote mudanças breaking
---
description: Deploy aplicação para ambiente
argument-hint: [environment] [version]
---
<!--
Uso: /deploy [staging|production] [version]
Requer: Credenciais AWS configuradas
Exemplo: /deploy staging v1.2.3
-->
Deploy aplicação para ambiente $1 usando versão $2...
Padrões Comuns
Padrão de Review
---
description: Revise mudanças de código
allowed-tools: Read, Bash(git:*)
---
Arquivos alterados: !`git diff --name-only`
Revise cada arquivo em busca de:
1. Qualidade de código e estilo
2. Bugs ou problemas potenciais
3. Cobertura de teste
4. Necessidades de documentação
Forneça feedback específico para cada arquivo.
Padrão de Testing
---
description: Execute testes para arquivo específico
argument-hint: [test-file]
allowed-tools: Bash(npm:*)
---
Execute testes: !`npm test $1`
Analise resultados e sugira correções para falhas.
Padrão de Documentação
---
description: Gere documentação para arquivo
argument-hint: [source-file]
---
Gere documentação abrangente para @$1 incluindo:
- Descrições de função/classe
- Documentação de parâmetro
- Descrições de valor retornado
- Exemplos de uso
- Casos extremos e erros
Padrão de Workflow
---
description: Workflow completo de PR
argument-hint: [pr-number]
allowed-tools: Bash(gh:*), Read
---
Workflow PR #$1:
1. Busque PR: !`gh pr view $1`
2. Revise mudanças
3. Execute verificações
4. Aprove ou solicite mudanças
Solução de Problemas
Command não aparece:
- Verifique se arquivo está no diretório correto
- Verifique se extensão
.mdestá presente - Garanta formato Markdown válido
- Reinicie Claude Code
Argumentos não funcionando:
- Verifique se sintaxe
$1,$2está correta - Verifique se
argument-hintcorresponde ao uso - Garanta sem espaços extras
Execução Bash falhando:
- Verifique se
allowed-toolsinclui Bash - Verifique sintaxe de comando em backticks
- Teste comando em terminal primeiro
- Verifique permissões necessárias
Referências de arquivo não funcionando:
- Verifique se sintaxe
@está correta - Verifique se caminho de arquivo é válido
- Garanta se ferramenta Read é permitida
- Use caminhos absolutos ou relativos ao projeto
Recursos Específicos de Plugin
Variável CLAUDE_PLUGIN_ROOT
Commands de plugin têm acesso a ${CLAUDE_PLUGIN_ROOT}, uma variável de ambiente que resolve para o caminho absoluto do plugin.
Propósito:
- Referencie arquivos de plugin portavelmente
- Execute scripts de plugin
- Carregue configuração de plugin
- Acesse templates de plugin
Uso básico:
---
description: Analise usando script de plugin
allowed-tools: Bash(node:*)
---
Execute análise: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`
Revise resultados e reporte achados.
Padrões comuns:
# Execute script de plugin
!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`
# Carregue configuração de plugin
@${CLAUDE_PLUGIN_ROOT}/config/settings.json
# Use template de plugin
@${CLAUDE_PLUGIN_ROOT}/templates/report.md
# Acesse recursos de plugin
@${CLAUDE_PLUGIN_ROOT}/docs/reference.md
Por que usar:
- Funciona em todas as instalações
- Portável entre sistemas
- Sem caminhos hardcoded necessários
- Essencial para plugins multi-arquivo
Organização de Plugin Command
Commands de plugin são descobertos automaticamente do diretório commands/:
plugin-name/
├── commands/
│ ├── foo.md # /foo (plugin:plugin-name)
│ ├── bar.md # /bar (plugin:plugin-name)
│ └── utils/
│ └── helper.md # /helper (plugin:plugin-name:utils)
└── plugin.json
Benefícios de namespacing:
- Agrupamento lógico de comando
- Mostrado em saída
/help - Evite conflitos de nome
- Organize comandos relacionados
Convenções de nomenclatura:
- Use nomes de ação descritivos
- Evite nomes genéricos (test, run)
- Considere prefixo específico do plugin
- Use hífens para nomes multi-palavra
Padrões de Plugin Command
Padrão baseado em configuração:
---
description: Deploy usando configuração de plugin
argument-hint: [environment]
allowed-tools: Read, Bash(*)
---
Carregue configuração: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json
Deploy para $1 usando configurações de definições.
Monitore deployment e reporte status.
Padrão baseado em template:
---
description: Gere docs de template
argument-hint: [component]
---
Template: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md
Gere documentação para $1 seguindo estrutura de template.
Padrão multi-script:
---
description: Workflow de build completo
allowed-tools: Bash(*)
---
Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
Test: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`
Package: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh`
Revise outputs e reporte status de workflow.
Veja references/plugin-features-reference.md para padrões detalhados.
Integração com Componentes de Plugin
Commands podem integrar com outros componentes de plugin para workflows poderosos.
Integração de Agent
Lance agents de plugin para tarefas complexas:
---
description: Revisão de código profunda
argument-hint: [file-path]
---
Inicie revisão abrangente de @$1 usando o agent code-reviewer.
O agent analisará:
- Estrutura de código
- Problemas de segurança
- Performance
- Melhores práticas
Agent usa recursos de plugin:
- ${CLAUDE_PLUGIN_ROOT}/config/rules.json
- ${CLAUDE_PLUGIN_ROOT}/checklists/review.md
Pontos-chave:
- Agent deve existir no diretório
plugin/agents/ - Claude usa ferramenta Task para lançar agent
- Documente capacidades de agent
- Referencie recursos de plugin que agent usa
Integração de Skill
Aproveite skills de plugin para conhecimento especializado:
---
description: Documente API com padrões
argument-hint: [api-file]
---
Documente API em @$1 seguindo padrões de plugin.
Use a skill api-docs-standards para garantir:
- Documentação completa de endpoint
- Formatação consistente
- Qualidade de exemplo
- Documentação de erro
Gere docs de API prontos para produção.
Pontos-chave:
- Skill deve existir no diretório
plugin/skills/ - Mencione nome de skill para disparar invocação
- Documente propósito de skill
- Explique o que skill fornece
Coordenação de Hook
Projete commands que funcionem com hooks de plugin:
- Commands podem preparar estado para hooks processarem
- Hooks executam automaticamente em eventos de ferramenta
- Commands devem documentar comportamento de hook esperado
- Guie Claude na interpretação de saída de hook
Veja references/plugin-features-reference.md para exemplos de commands que coordenam com hooks
Workflows Multi-Componente
Combine agents, skills e scripts:
---
description: Workflow de revisão abrangente
argument-hint: [file]
allowed-tools: Bash(node:*), Read
---
Alvo: @$1
Fase 1 - Análise Estática:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`
Fase 2 - Revisão Profunda:
Lance agent code-reviewer para análise detalhada.
Fase 3 - Verificação de Padrões:
Use skill coding-standards para validação.
Fase 4 - Relatório:
Template: @${CLAUDE_PLUGIN_ROOT}/templates/review.md
Compile achados em relatório seguindo template.
Quando usar:
- Workflows multi-passo complexos
- Aproveite múltiplas capacidades de plugin
- Requer análise especializada
- Necessite saídas estruturadas
Padrões de Validação
Commands devem validar entradas e recursos antes de processar.
Validação de Argumento
---
description: Deploy com validação
argument-hint: [environment]
---
Valide ambiente: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"`
Se $1 é ambiente válido:
Deploy para $1
Caso contrário:
Explique ambientes válidos: dev, staging, prod
Mostre uso: /deploy [environment]
Verificações de Existência de Arquivo
---
description: Processe configuração
argument-hint: [config-file]
---
Verifique se arquivo existe: !`test -f $1 && echo "EXISTS" || echo "MISSING"`
Se arquivo existe:
Processe configuração: @$1
Caso contrário:
Explique onde colocar arquivo de config
Mostre formato esperado
Forneça exemplo de configuração
Validação de Recurso de Plugin
---
description: Execute analisador de plugin
allowed-tools: Bash(test:*)
---
Valide setup de plugin:
- Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" || echo "✗"`
- Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" || echo "✗"`
Se todas as verificações passam, execute análise.
Caso contrário, reporte componentes ausentes.
Tratamento de Erro
---
description: Build com tratamento de erro
allowed-tools: Bash(*)
---
Execute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 || echo "BUILD_FAILED"`
Se build sucedeu:
Reporte sucesso e localização de output
Se build falhou:
Analise saída de erro
Sugira causas prováveis
Forneça etapas de solução de problemas
Melhores práticas:
- Valide cedo no comando
- Forneça mensagens de erro úteis
- Sugira ações corretivas
- Lide com casos extremos graciosamente
Para especificações detalhadas de campo frontmatter, veja references/frontmatter-reference.md.
Para recursos específicos de plugin e padrões, veja references/plugin-features-reference.md.
Para exemplos de padrão de comando, veja diretório examples/.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |