Skills e slash commands: criar seus próprios workflows

# Moderna (2026): diretório dedicado com arquivos de suporte
.claude/skills/
├── deploy/
│   ├── SKILL.md           # entrada principal (frontmatter + instruções)
│   ├── reference.md       # referências que Claude consulta quando precisa
│   ├── examples.md        # exemplos de uso
│   └── scripts/
│       ├── validate.sh    # Claude pode executar
│       └── rollback.sh
└── pr-review/
    ├── SKILL.md
    └── checklist.md

# Clássica (ainda suportada): arquivo único
.claude/commands/deploy.md   # equivale a .claude/skills/deploy/SKILL.md

# Hierarquia de discovery (em ordem de prioridade):
# 1. Plugins (namespace: plugin-name:skill-name)
# 2. .claude/skills/ do projeto
# 3. ~/.claude/skills/ do usuário
# 4. Enterprise managed skills
# 5. .claude/commands/ legacy (projeto)
# 6. ~/.claude/commands/ legacy (usuário)

# Comandos de gestão:
/skills                     # lista skills disponíveis (press 't' pra sort by token)
/agents                     # UI pra criar/editar agents (similar)

# Restrições de tamanho:
# - description: até 1536 chars (incluindo when_to_use)
# - Skill content: fica na conversa; skills invocadas compartilham budget de 25k tokens

# Skills ficam em .claude/commands/ como arquivos Markdown
# Nome do arquivo = nome do comando (sem .md)

# Exemplo: .claude/commands/commit.md → /commit
# Exemplo: .claude/commands/code-review.md → /code-review
# Exemplo: .claude/commands/deploy.md → /deploy staging v2.1

# Estrutura de um arquivo de skill:

---
# Este bloco de frontmatter é opcional mas recomendado
description: Cria um commit com mensagem no formato Conventional Commits
---

Analise as mudanças staged com `git diff --staged` e crie um commit seguindo estas regras:

1. Formato: `tipo(escopo): descrição curta em PT-BR`
   - tipos: feat, fix, refactor, docs, test, chore, style, perf
   - escopo: componente ou módulo afetado (opcional)
   - descrição: máximo 72 caracteres, imperativo, sem ponto final

2. Se as mudanças cobrem múltiplos contextos, use commit com bullet points no body.

3. Nunca use --no-verify. Se o pre-commit falhar, investigue e corrija.

4. Após o commit bem-sucedido, confirme com: "✓ Commit criado: [mensagem]"

# Para invocar: /commit
# Claude Code carrega este arquivo, injetado como prompt do usuário

# .claude/commands/pr-review.md
# Uso: /pr-review 42 ou /pr-review https://github.com/org/repo/pull/42

Revise o Pull Request: $ARGUMENTS

Processo:
1. Use o MCP do GitHub para buscar o PR (número ou URL fornecido)
2. Leia o diff completo
3. Analise por estas dimensões (sem ser condescendente ou genérico):
   - Segurança: há possibilidade de injeção, vazamento de dados, permissão indevida?
   - Performance: loops O(n²), N+1 queries, blocking I/O desnecessário?
   - Manutenibilidade: a lógica está clara? há duplicação evitável?
   - Cobertura de edge cases: o que acontece com inputs inválidos, lista vazia, null?
   - Alinhamento com padrões do projeto (cheque o CLAUDE.md para convenções)

4. Formato da resposta:
   ### ✅ Aprovado / ⚠️ Mudanças necessárias / ❌ Bloqueado

   **Problemas críticos** (bloqueia merge):
   - ...

   **Sugestões** (não bloqueia, mas vale considerar):
   - ...

   **Pontos positivos** (o que está bem feito):
   - ...

5. Se não há problemas: "Aprovado ✅ — PR pode ser mergeado"

---
# .claude/commands/new-component.md
# Uso: /new-component NomeDoComponente

Crie um novo componente React: $ARGUMENTS

Siga o padrão dos componentes existentes em src/components/:
1. Leia 2-3 componentes similares para entender o padrão usado
2. Crie src/components/$ARGUMENTS.tsx com:
   - Props tipadas (interface ou type)
   - JSDoc na interface de Props
   - Named export (não default export)
   - Sem estado interno se possível (prefira componentes controlados)
3. Exporte no src/components/index.ts se existir
4. Confirme o que foi criado e próximos passos

# .claude/commands/deploy.md
# Uso: /deploy staging ou /deploy production

Executar deploy no ambiente: $ARGUMENTS

ATENÇÃO: Se o ambiente for "production", exija confirmação explícita antes de qualquer ação.

Checklist antes de qualquer deploy:
1. Verificar que não há mudanças não commitadas: git status
2. Verificar que os testes passam: npm test
3. Verificar que o build está limpo: npm run build
4. Para produção: verificar que está na branch main e o último commit é recente

Se algum item do checklist falhar, PARE e informe o problema. Não continue o deploy.

Se o ambiente for "staging":
- Execute: ./scripts/deploy.sh staging
- Aguarde confirmação de sucesso
- Reporte a URL de staging ao final

Se o ambiente for "production":
- Exiba o checklist e peça confirmação explícita: "Confirme digitando 'DEPLOY PRODUCTION'"
- Só prossiga após confirmação textual explícita
- Execute: ./scripts/deploy.sh production
- Monitore o rollout por 5 minutos
- Verifique os health checks configurados

# Dois locais para skills:

# 1. ~/.claude/commands/ — globais (disponíveis em TODOS os projetos)
~/.claude/commands/
├── commit.md              # /commit — padrão pessoal de commit
├── explain.md             # /explain — explique o código selecionado
└── quick-doc.md           # /quick-doc — gera docstring rapidamente

# 2. .claude/commands/ (projeto) — compartilhados com o time via git
.claude/commands/
├── deploy.md              # /deploy — específico deste projeto
├── pr-review.md           # /pr-review — padrões de review da equipe
├── new-component.md       # /new-component — padrão de componente React do projeto
└── security-check.md      # /security-check — checklist de segurança do projeto

# Regra de prioridade:
# - Skills de projeto têm prioridade sobre globais com mesmo nome
# - /commit no projeto pode sobrescrever /commit global se tiver convenções diferentes

# Descobrir skills disponíveis na sessão:
/help    # lista todos os comandos disponíveis, incluindo seus skills customizados

# Boas práticas de skills:
# ✅ Instrua Claude a ler arquivos relevantes antes de agir (contexto primeiro)
# ✅ Defina formato de saída esperado (evita variação entre execuções)
# ✅ Adicione checklist para ações destrutivas (deploy, deletar dados)
# ✅ Documente no CLAUDE.md quais skills existem e para que servem
# ❌ Não crie skills muito genéricos ("faça o que for necessário") — seja específico
# ❌ Não duplique o que o CLAUDE.md já cobre — skills são para workflows, não contexto

# .claude/commands/spec.md
# Uso: /spec [feature] — gera especificação técnica antes de implementar

Gere uma especificação técnica para: $ARGUMENTS

Antes de escrever qualquer código, produza um documento SPEC.md com:

## 1. Problema
O que estamos resolvendo? Por que isso importa?

## 2. Decisões de design
- Quais são as 2-3 abordagens possíveis?
- Para cada uma: trade-offs, complexidade, manutenabilidade
- Decisão escolhida e justificativa

## 3. Interface pública
- Quais funções/componentes/rotas serão criados/modificados?
- Tipos e assinaturas exatas
- Exemplos de uso

## 4. Casos de borda
- O que acontece com input inválido?
- O que acontece com falha de rede/banco?
- Limites de volume (quantos usuários, quantos registros)

## 5. Plano de implementação
- Passos ordenados de implementação
- Quais arquivos criar/modificar
- Estimativa de complexidade (S/M/L/XL)

## 6. Critérios de aceite
- Como verificar que está funcionando?
- Quais testes cobrir?

---
Após gerar o SPEC.md, aguarde aprovação antes de começar a implementação.
Escreva: "Especificação gerada em SPEC.md. Revise e diga 'implementar' para prosseguir."

---
name: code-migration                        # identificador (lowercase, max 64 chars)
description: |                              # quando Claude invoca automaticamente
  Migra código legado para arquitetura nova.
  Use quando arquivos usarem padrões deprecated ou
  quando o usuário pedir migração de módulo.
when_to_use: |                              # appended à description
  Evite invocar se o arquivo já está na arquitetura nova.

argument-hint: "[arquivo] [target-arch]"    # hint visual no TUI

# Controle de invocação
disable-model-invocation: false             # só usuário pode invocar (via /skill-name)
user-invocable: true                        # usuário pode digitar /skill-name
paths: "src/legacy/**,src/old/**"           # só ativa para esses paths

# Controle de execução
allowed-tools: "Read Edit Bash(git *)"      # pré-aprova tools (sem permission prompt)
model: claude-opus-4-7                      # override do modelo
effort: high                                # override do effort level
context: fork                               # roda em subagent isolado
agent: general-purpose                      # tipo de subagent quando context:fork
shell: bash                                 # shell pra !`cmd` (bash|powershell)

# Hooks específicos desta skill (só rodam durante)
hooks:
  PreToolUse:
    - matcher: Edit
      hooks:
        - type: command
          command: "./scripts/lint-check.sh"
---

## Instruções em markdown

Instruções da skill aqui. Claude vai seguir durante a invocação.

Variáveis disponíveis:
- $ARGUMENTS — todos os args passados
- $1, $2, $N — argumento específico (0-indexed: $0 = primeiro)
- ${CLAUDE_SESSION_ID} — ID da sessão atual
- ${CLAUDE_SKILL_DIR} — path da pasta desta skill (útil pra ler reference.md)

---
name: release-notes
description: Gera changelog baseado em commits desde última tag
allowed-tools: "Read Bash(git *)"
---

# Release Notes

Gere changelog formatado a partir dos dados reais abaixo.
Esses valores são puxados NO MOMENTO da invocação:

**Última tag:** !`git describe --tags --abbrev=0`

**Commits desde então:**
!`git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges`

**Branch atual:** !`git branch --show-current`

**Data:** !`date +%Y-%m-%d`

**Arquivos alterados:**
!`git diff --stat $(git describe --tags --abbrev=0)..HEAD`

## Instruções

1. Agrupe commits em categorias (feat/fix/docs/chore)
2. Escreva em português, tom editorial
3. Destaque breaking changes em seção separada
4. Inclua contador de PRs mergeados por tipo

# O que acontece:
# 1. Claude executa cada !`cmd` e substitui o output no markdown
# 2. Só depois vê a skill "cozida" com os dados reais
# 3. Então segue as instruções

# Multi-line: use fence code block com !
```!
git log --since="1 week ago" --pretty=format:"%h %s (%an)"
```

# Estrutura completa de uma skill de deploy
.claude/skills/deploy/
├── SKILL.md              # entrada (referência os arquivos abaixo)
├── reference.md          # detalhes que Claude consulta quando precisa
├── checklist.md          # checklist pré-deploy
└── scripts/
    ├── validate.sh       # Claude executa via Bash
    ├── rollback.sh
    └── health-check.sh

# SKILL.md:
---
name: deploy
description: Deploy completo com validação e rollback
allowed-tools: "Bash Read"
argument-hint: "[staging|production] [version]"
---

# Deploy

Ambiente: $1
Versão: $2

## Pré-deploy
Leia ${CLAUDE_SKILL_DIR}/checklist.md e execute cada item.

## Execução
1. Execute: bash ${CLAUDE_SKILL_DIR}/scripts/validate.sh $1
2. Se validação OK, execute: bash ${CLAUDE_SKILL_DIR}/scripts/deploy.sh $1 $2
3. Aguarde 30s, execute: bash ${CLAUDE_SKILL_DIR}/scripts/health-check.sh $1

## Rollback automático
Se qualquer health check falhar, execute IMEDIATAMENTE:
bash ${CLAUDE_SKILL_DIR}/scripts/rollback.sh $1

## Referência técnica
Consulte ${CLAUDE_SKILL_DIR}/reference.md para detalhes de
cada ambiente (URLs, credentials path, rollback strategy).

# Vantagens desta estrutura:
# - Scripts testáveis isoladamente (bash validate.sh staging)
# - Reference.md só é lido quando Claude precisa (não polui contexto sempre)
# - Checklist.md serve tanto pra Claude quanto pra dev humano
# - Versionamento: tudo no git, time inteiro tem os mesmos scripts