Skills avançadas: scripts auxiliares, dynamic context e hooks scoped

---
# Identificação (obrigatórios ou quase)
name: release-manager                       # lowercase, max 64 chars, único no escopo
description: |                              # o que faz + quando usar (max 1536 chars incluindo when_to_use)
  Gera release completa: changelog, notas, tag git, PR do release.
  Use quando houver commits desde última tag e for hora de releasear.
when_to_use: |                              # appended à description
  Evite rodar se CI estiver quebrado ou se há PRs em flight não mergeados.

# UX
argument-hint: "[major|minor|patch]"        # exibido no TUI
icon: "🚀"                                  # emoji no picker

# Invocação
disable-model-invocation: false             # se true, só usuário invoca
user-invocable: true                        # se false, só Claude invoca (autopilot)
paths: "**"                                 # glob pra auto-suggest (opcional)

# Execução
allowed-tools: "Read Bash(git *) Edit(CHANGELOG.md) Write(docs/releases/**)"
model: claude-opus-4-7                      # override do modelo (opcional)
effort: high                                # override de effort level
context: fork                               # executa em subagent isolado
agent: general-purpose                      # tipo de subagent quando context: fork
shell: bash                                 # shell pra !`cmd` blocks (bash|powershell)

# Hooks scoped (só ativam durante execução desta skill)
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: ".claude/skills/release-manager/scripts/pre-check.sh"
          timeout: 30
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: ".claude/skills/release-manager/scripts/verify.sh"
  Stop:
    - matcher: ".*"
      hooks:
        - type: http
          url: "${SLACK_RELEASE_WEBHOOK}"
          allowedEnvVars: ["SLACK_RELEASE_WEBHOOK"]
---

# Release Manager

Bump de versão: $1 (major|minor|patch)

## Estado atual
- Última tag: !`git describe --tags --abbrev=0`
- Branch: !`git branch --show-current`
- Commits desde tag: !`git rev-list --count $(git describe --tags --abbrev=0)..HEAD`
- Arquivos alterados: !`git diff --stat $(git describe --tags --abbrev=0)..HEAD | tail -1`

## Procedimento

1. Pre-check: bash ${CLAUDE_SKILL_DIR}/scripts/pre-check.sh
2. Gere CHANGELOG.md novo usando ${CLAUDE_SKILL_DIR}/reference/changelog-template.md
3. Calcule nova versão baseado em $1
4. Commit: "chore(release): v<nova-versão>"
5. Tag: v<nova-versão>
6. Abra PR de release com notas geradas
7. Notificação Slack automática via Stop hook

## Erros comuns
Consulte ${CLAUDE_SKILL_DIR}/reference/common-errors.md

.claude/skills/release-manager/
├── SKILL.md                      # entrada principal (frontmatter + instruções)
├── reference/
│   ├── changelog-template.md     # template que Claude consulta quando precisa
│   ├── common-errors.md          # erros conhecidos e como resolver
│   ├── api-reference.md          # referência técnica detalhada
│   └── examples/
│       ├── release-minor.md      # exemplo completo de release minor
│       └── release-major.md      # exemplo com breaking changes
├── scripts/
│   ├── pre-check.sh              # Claude executa via Bash
│   ├── verify.sh
│   ├── bump-version.sh
│   └── notify-slack.sh
└── tests/
    └── dry-run.sh                # testa a skill sem side effects

# Vantagens desta estrutura:
# 1. SKILL.md curto e focado (menos tokens no contexto)
# 2. Reference files lazy-loaded: Claude só lê quando precisa
# 3. Scripts testáveis isoladamente (bash scripts/pre-check.sh dry-run)
# 4. Versionamento: tudo no git, time inteiro tem o mesmo workflow
# 5. Onboarding: novo dev lê SKILL.md + examples/ pra entender

# Convenção sugerida:
# - SKILL.md: < 200 linhas
# - Reference individual: < 500 linhas
# - Scripts: testáveis isoladamente, bem documentados

# Variantes de dynamic context injection:

## 1. Inline com crase backticks
Branch atual: !`git branch --show-current`
Commits hoje: !`git log --since=midnight --oneline | wc -l`

## 2. Multi-line com fence
```!
git log --since="1 week ago" --pretty=format:"%h %s (%an)" | head -20
```

## 3. Encadeamento
PRs mergeados essa semana: !`gh pr list --state merged --search "merged:>=$(date -d 'last monday' +%Y-%m-%d)" --json number | jq length`

## 4. Com processamento
Top contribuidores: !`git log --format='%an' --since='1 month ago' | sort | uniq -c | sort -rn | head -5`

## 5. Condicionais (via script)
Status do deploy: !`[ -f .deploy-status ] && cat .deploy-status || echo "sem info"`

# IMPORTANTE:
# - !`cmd` executa ANTES de a skill ser processada
# - Output substitui o literal no markdown
# - Claude vê apenas o texto resultante (não o comando)
# - Erros: stderr vai pro Claude como parte do contexto
# - Timeout: usa timeout padrão do shell do sistema

# Quando NÃO usar:
# - Comandos lentos (> 2s) poluem o startup da skill
# - Dados sensíveis (tokens): use ${CLAUDE_SKILL_DIR}/reference/ em vez
# - Comandos com efeito colateral: reserve pros Bash tool calls depois

---
name: deep-research
description: Pesquisa profunda em codebase sem poluir contexto
context: fork                              # ← crítico
agent: Explore
allowed-tools: "Read Glob Grep"
argument-hint: "[tópico de pesquisa]"
---

# Deep Research: $ARGUMENTS

Você é um subagent Explore dedicado à pesquisa.

Sua tarefa: mapear todo o uso de "$ARGUMENTS" no codebase.

Processo:
1. Use Glob pra listar arquivos relevantes
2. Use Grep pra encontrar ocorrências
3. Para cada ocorrência crítica, use Read pra ler contexto
4. Monte um relatório estruturado

Formato de output (SÓ retorne isso pro principal):
```
## Ocorrências de "$ARGUMENTS"

### Arquivo: <path>
- **Linha N**: <contexto em 1 frase>
- **Linha M**: <contexto em 1 frase>

### Arquivo: <path>
- ...

## Padrões identificados
- <padrão 1>
- <padrão 2>

## Recomendação
<1 parágrafo>
```

NÃO retorne conteúdo bruto dos arquivos — só resumos e referencias.

# .claude/skills/deploy/SKILL.md
---
name: deploy
description: Deploy com validação pré + verificação pós + notificação
allowed-tools: "Bash Read"
argument-hint: "[staging|production]"
hooks:
  # Hooks aqui ativam APENAS durante execução desta skill.
  # Acabando a skill, eles somem — não afetam outras sessões.

  UserPromptSubmit:
    - hooks:
        - type: command
          command: "bash ${CLAUDE_SKILL_DIR}/scripts/inject-context.sh"
          # Injeta contexto de deploy (último deploy, versão atual, etc.)

  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "bash ${CLAUDE_SKILL_DIR}/scripts/pre-deploy-check.sh"
          timeout: 60
          # Valida: branch main, sem mudanças, testes passando, approval obtido

  PostToolUse:
    - matcher: "Bash(./deploy.sh:*)"
      hooks:
        - type: command
          command: "bash ${CLAUDE_SKILL_DIR}/scripts/post-deploy-verify.sh"
          # Health checks, smoke tests, métricas de latência

  Stop:
    - matcher: ".*"
      hooks:
        - type: http
          url: "${SLACK_RELEASES_WEBHOOK}"
          allowedEnvVars: ["SLACK_RELEASES_WEBHOOK"]
          # Notifica o time ao terminar o deploy

  # Agents/Tasks hooks (2026):
  SubagentStart:
    - hooks:
        - type: command
          command: "echo 'Subagent spawned for deploy' >> ${CLAUDE_SKILL_DIR}/../audit.log"
---

# Deploy

Execute deploy no ambiente: $1

Procedimento:
1. Pre-check é automático (hook PreToolUse). Você só executa ./deploy.sh $1.
2. Post-check é automático (hook PostToolUse após deploy.sh).
3. Notificação é automática (hook Stop).

Sua responsabilidade:
- Confirmar o ambiente com o usuário se for production
- Executar o comando correto baseado em $1
- Reportar resultado final ao usuário