Skill Developer

Guia do Desenvolvedor de Skills

Propósito

Guia completo para criar e gerenciar skills em Claude Code com sistema de auto-ativação, seguindo as melhores práticas oficiais da Anthropic, incluindo a regra de 500 linhas e padrão de divulgação progressiva.

Quando Usar Esta Skill

Ativa automaticamente quando você menciona:

• Criar ou adicionar skills
• Modificar triggers ou regras de skill
• Entender como a ativação de skill funciona
• Debugar problemas de ativação de skill
• Trabalhar com skill-rules.json
• Mecânica do sistema de hooks
• Melhores práticas de Claude Code
• Divulgação progressiva
• Frontmatter YAML
• Regra de 500 linhas

Visão Geral do Sistema

Arquitetura de Dois Hooks

1. Hook UserPromptSubmit (Sugestões Proativas)

• Arquivo: .claude/hooks/skill-activation-prompt.ts
• Ativação: ANTES de Claude ver o prompt do usuário
• Propósito: Sugerir skills relevantes com base em palavras-chave + padrões de intenção
• Método: Injeta lembrança formatada como contexto (stdout → entrada de Claude)
• Casos de uso: Skills baseadas em tópico, detecção de trabalho implícito

2. Stop Hook - Lembretes de Tratamento de Erros (Lembretes Suaves)

• Arquivo: .claude/hooks/error-handling-reminder.ts
• Ativação: DEPOIS que Claude termina de responder
• Propósito: Lembrança suave para auto-avaliar tratamento de erros no código escrito
• Método: Analisa arquivos editados para padrões arriscados, exibe lembrança se necessário
• Casos de uso: Consciência de tratamento de erros sem bloquear fluxo de trabalho

Mudança de Filosofia (2025-10-27): Abandonamos o bloqueio PreToolUse para Sentry/tratamento de erros. Em vez disso, use lembretes suaves pós-resposta que não bloqueiam o fluxo de trabalho mas mantêm consciência de qualidade de código.

Arquivo de Configuração

Localização: .claude/skills/skill-rules.json

Define:

• Todas as skills e suas condições de ativação
• Níveis de enforcement (block, suggest, warn)
• Padrões de caminho de arquivo (glob)
• Padrões de detecção de conteúdo (regex)
• Condições de skip (rastreamento de sessão, marcadores de arquivo, variáveis de ambiente)

Tipos de Skill

1. Skills de Proteção (Guardrail)

Propósito: Enforçar melhores práticas críticas que previnem erros

Características:

• Tipo: "guardrail"
• Enforcement: "block"
• Prioridade: "critical" ou "high"
• Bloqueia edições de arquivo até a skill ser usada
• Previne erros comuns (nomes de coluna, erros críticos)
• Consciência de sessão (não repete nag na mesma sessão)

Exemplos:

• database-verification - Verificar nomes de tabela/coluna antes de queries Prisma
• frontend-dev-guidelines - Enforçar padrões React/TypeScript

Quando Usar:

• Erros que causam falhas em runtime
• Problemas de integridade de dados
• Problemas críticos de compatibilidade

2. Skills de Domínio

Propósito: Fornecer orientação abrangente para áreas específicas

Características:

• Tipo: "domain"
• Enforcement: "suggest"
• Prioridade: "high" ou "medium"
• Advisory, não obrigatório
• Específico de tópico ou domínio
• Documentação abrangente

Exemplos:

• backend-dev-guidelines - Padrões Node.js/Express/TypeScript
• frontend-dev-guidelines - Melhores práticas React/TypeScript
• error-tracking - Orientação de integração Sentry

Quando Usar:

• Sistemas complexos que exigem conhecimento profundo
• Documentação de melhores práticas
• Padrões arquiteturais
• Guias de como fazer

Quick Start: Criando uma Nova Skill

Passo 1: Criar Arquivo de Skill

Localização: .claude/skills/{nome-skill}/SKILL.md

Template:

---
name: minha-nova-skill
description: Breve descrição incluindo palavras-chave que ativam esta skill. Mencione tópicos, tipos de arquivo e casos de uso. Seja explícito sobre termos de ativação.
---

# Minha Nova Skill

## Propósito
O que esta skill ajuda

## Quando Usar
Cenários e condições específicas

## Informações-Chave
A orientação real, documentação, padrões, exemplos

Melhores Práticas:

• ✅ Nome: Minúsculas, hífens, forma gerúndio preferida (verbo + -ing)
• ✅ Descrição: Incluir TODAS as palavras-chave/frases de ativação (máx. 1024 caracteres)
• ✅ Conteúdo: Menos de 500 linhas - use arquivos de referência para detalhes
• ✅ Exemplos: Exemplos de código real
• ✅ Estrutura: Headings claros, listas, blocos de código

Passo 2: Adicionar a skill-rules.json

Veja SKILL_RULES_REFERENCE.md para schema completo.

Template Básico:

{
  "minha-nova-skill": {
    "type": "domain",
    "enforcement": "suggest",
    "priority": "medium",
    "promptTriggers": {
      "keywords": ["palavra-chave1", "palavra-chave2"],
      "intentPatterns": ["(criar|adicionar).*?algo"]
    }
  }
}

Passo 3: Testar Triggers

Testar UserPromptSubmit:

echo '{"session_id":"test","prompt":"seu prompt de teste"}' | \
  npx tsx .claude/hooks/skill-activation-prompt.ts

Testar PreToolUse:

cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts
{"session_id":"test","tool_name":"Edit","tool_input":{"file_path":"test.ts"}}
EOF

Passo 4: Refinar Padrões

Com base nos testes:

• Adicionar palavras-chave faltantes
• Refinar padrões de intenção para reduzir falsos positivos
• Ajustar padrões de caminho de arquivo
• Testar padrões de conteúdo contra arquivos reais

Passo 5: Seguir Melhores Práticas da Anthropic

✅ Manter SKILL.md menor que 500 linhas ✅ Usar divulgação progressiva com arquivos de referência ✅ Adicionar índice a arquivos de referência > 100 linhas ✅ Escrever descrição detalhada com palavras-chave de ativação ✅ Testar com 3+ cenários reais antes de documentar ✅ Iterar com base no uso real

Níveis de Enforcement

BLOCK (Proteções Críticas)

• Previne fisicamente execução da ferramenta Edit/Write
• Código de saída 2 do hook, stderr → Claude
• Claude vê mensagem e deve usar a skill para prosseguir
• Use Para: Erros críticos, integridade de dados, problemas de segurança

Exemplo: Verificação de nome de coluna de banco de dados

SUGGEST (Recomendado)

• Lembrança injetada antes de Claude ver o prompt
• Claude está ciente de skills relevantes
• Não enforçado, apenas advisory
• Use Para: Orientação de domínio, melhores práticas, guias de como fazer

Exemplo: Diretrizes de desenvolvimento frontend

WARN (Opcional)

• Sugestões de baixa prioridade
• Apenas advisory, enforcement mínimo
• Use Para: Sugestões úteis, lembretes informativos

Raramente usado - a maioria das skills são BLOCK ou SUGGEST.

Condições de Skip & Controle do Usuário

1. Rastreamento de Sessão

Propósito: Não incomodar repetidamente na mesma sessão

Como funciona:

• Primeira edição → Hook bloqueia, atualiza estado de sessão
• Segunda edição (mesma sessão) → Hook permite
• Sessão diferente → Bloqueia novamente

Arquivo de Estado: .claude/hooks/state/skills-used-{session_id}.json

2. Marcadores de Arquivo

Propósito: Skip permanente para arquivos verificados

Marcador: // @skip-validation

Uso:

// @skip-validation
import { PrismaService } from './prisma';
// Este arquivo foi verificado manualmente

NOTA: Use com moderação - derrota o propósito se usado em excesso

3. Variáveis de Ambiente

Propósito: Desabilitar de emergência, override temporário

Desabilitar globalmente:

export SKIP_SKILL_GUARDRAILS=true  # Desabilita TODOS os blocos PreToolUse

Específico de skill:

export SKIP_DB_VERIFICATION=true
export SKIP_ERROR_REMINDER=true

Checklist de Teste

Ao criar uma nova skill, verifique:

• Arquivo de skill criado em .claude/skills/{nome}/SKILL.md
• Frontmatter apropriado com name e description
• Entrada adicionada a skill-rules.json
• Palavras-chave testadas com prompts reais
• Padrões de intenção testados com variações
• Padrões de caminho de arquivo testados com arquivos reais
• Padrões de conteúdo testados contra conteúdo de arquivo
• Mensagem de bloqueio é clara e acionável (se guardrail)
• Condições de skip configuradas apropriadamente
• Nível de prioridade corresponde à importância
• Sem falsos positivos nos testes
• Sem falsos negativos nos testes
• Performance aceitável (<100ms ou <200ms)
• Sintaxe JSON validada: jq . skill-rules.json
• SKILL.md menor que 500 linhas ⭐
• Arquivos de referência criados se necessário
• Índice adicionado a arquivos > 100 linhas

Arquivos de Referência

Para informações detalhadas sobre tópicos específicos, veja:

TRIGGER_TYPES.md

Guia completo para todos os tipos de trigger:

• Triggers de palavra-chave (correspondência explícita de tópico)
• Padrões de intenção (detecção implícita de ação)
• Triggers de caminho de arquivo (padrões glob)
• Padrões de conteúdo (regex em arquivos)
• Melhores práticas e exemplos para cada
• Armadilhas comuns e estratégias de teste

SKILL_RULES_REFERENCE.md

Schema completo de skill-rules.json:

• Definições completas de interface TypeScript
• Explicações campo a campo
• Exemplo completo de skill guardrail
• Exemplo completo de skill de domínio
• Guia de validação e erros comuns

HOOK_MECHANISMS.md

Mergulho profundo nos internals de hooks:

• Fluxo UserPromptSubmit (detalhado)
• Fluxo PreToolUse (detalhado)
• Tabela de comportamento de código de saída (CRÍTICO)
• Gerenciamento de estado de sessão
• Considerações de performance

TROUBLESHOOTING.md

Guia abrangente de debugging:

• Skill não está ativando (UserPromptSubmit)
• PreToolUse não está bloqueando
• Falsos positivos (muitos triggers)
• Hook não está executando
• Problemas de performance

PATTERNS_LIBRARY.md

Coleção de padrões prontos para usar:

• Biblioteca de padrões de intenção (regex)
• Biblioteca de padrões de caminho de arquivo (glob)
• Biblioteca de padrões de conteúdo (regex)
• Organizado por caso de uso
• Pronto para copiar e colar

ADVANCED.md

Aprimoramentos futuros e ideias:

• Atualizações de regras dinâmicas
• Dependências de skill
• Enforcement condicional
• Analytics de skill
• Versionamento de skill

Resumo de Referência Rápida

Criar Nova Skill (5 Passos)

1. Criar .claude/skills/{nome}/SKILL.md com frontmatter
2. Adicionar entrada a .claude/skills/skill-rules.json
3. Testar com comandos npx tsx
4. Refinar padrões com base em testes
5. Manter SKILL.md menor que 500 linhas

Tipos de Trigger

• Palavras-chave: Menções explícitas de tópico
• Intenção: Detecção implícita de ação
• Caminhos de Arquivo: Ativação baseada em localização
• Conteúdo: Detecção específica de tecnologia

Veja TRIGGER_TYPES.md para detalhes completos.

Enforcement

• BLOCK: Código de saída 2, apenas crítico
• SUGGEST: Injetar contexto, mais comum
• WARN: Advisory, raramente usado

Condições de Skip

• Rastreamento de sessão: Automático (previne nags repetidos)
• Marcadores de arquivo: // @skip-validation (skip permanente)
• Variáveis de env: SKIP_SKILL_GUARDRAILS (desabilitar de emergência)

Melhores Práticas da Anthropic

✅ Regra de 500 linhas: Manter SKILL.md menor que 500 linhas ✅ Divulgação progressiva: Usar arquivos de referência para detalhes ✅ Índice: Adicionar a arquivos de referência > 100 linhas ✅ Um nível profundo: Não aninhar referências profundamente ✅ Descrições ricas: Incluir todas as palavras-chave de ativação (máx. 1024 caracteres) ✅ Testar primeiro: Construir 3+ avaliações antes de documentação extensa ✅ Naming em gerúndio: Preferir verbo + -ing (ex: "processando-pdfs")

Debugar

Testar hooks manualmente:

# UserPromptSubmit
echo '{"prompt":"teste"}' | npx tsx .claude/hooks/skill-activation-prompt.ts

# PreToolUse
cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts
{"tool_name":"Edit","tool_input":{"file_path":"test.ts"}}
EOF

Veja TROUBLESHOOTING.md para guia completo de debugging.

Arquivos Relacionados

Configuração:

• .claude/skills/skill-rules.json - Configuração mestre
• .claude/hooks/state/ - Rastreamento de sessão
• .claude/settings.json - Registro de hooks

Hooks:

• .claude/hooks/skill-activation-prompt.ts - UserPromptSubmit
• .claude/hooks/error-handling-reminder.ts - Evento Stop (lembretes suaves)

Todas as Skills:

• .claude/skills/*/SKILL.md - Arquivos de conteúdo de skill

Status de Skill: COMPLETO - Reestruturado seguindo melhores práticas da Anthropic ✅ Contagem de Linhas: < 500 (seguindo regra de 500 linhas) ✅ Divulgação Progressiva: Arquivos de referência para informações detalhadas ✅

Próximo: Criar mais skills, refinar padrões com base no uso