Guia do Desenvolvedor de Habilidades

Propósito

Guia abrangente para criar e gerenciar habilidades no Claude Code com sistema de ativação automática, seguindo as melhores práticas oficiais da Anthropic, incluindo a regra das 500 linhas e o padrão de divulgação progressiva.

Quando Usar Esta Habilidade

Ativa automaticamente quando você menciona:

• Criar ou adicionar habilidades
• Modificar gatilhos ou regras de habilidades
• Entender como a ativação de habilidades funciona
• Depurar problemas de ativação de habilidades
• Trabalhar com skill-rules.json
• Mecânicas do sistema de hooks
• Melhores práticas do Claude Code
• Divulgação progressiva
• YAML frontmatter
• Regra das 500 linhas

Visão Geral do Sistema

Arquitetura de Dois Hooks

1. Hook UserPromptSubmit (Sugestões Proativas)

• Arquivo: .claude/hooks/skill-activation-prompt.ts
• Gatilho: ANTES do Claude ver o prompt do usuário
• Propósito: Sugerir habilidades relevantes com base em palavras-chave + padrões de intenção
• Método: Injeta um lembrete formatado como contexto (stdout → entrada do Claude)
• Casos de Uso: Habilidades baseadas em tópicos, detecção de trabalho implícito

2. Hook Stop - Lembrete de Tratamento de Erros (Lembretes Gentis)

• Arquivo: .claude/hooks/error-handling-reminder.ts
• Gatilho: APÓS o Claude terminar de responder
• Propósito: Lembrete gentil para autoavaliar o tratamento de erros no código escrito
• Método: Analisa arquivos editados em busca de padrões arriscados, exibe lembrete se necessário
• Casos de Uso: Conscientização sobre tratamento de erros sem bloquear o fluxo de trabalho

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

Arquivo de Configuração

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

Define:

• Todas as habilidades e suas condições de gatilho
• Níveis de aplicação (bloquear, sugerir, avisar)
• Padrões de caminho de arquivo (glob)
• Padrões de detecção de conteúdo (regex)
• Condições de omissão (rastreamento de sessão, marcadores de arquivo, variáveis de ambiente)

Tipos de Habilidades

1. Habilidades de Proteção (Guardrail Skills)

Propósito: Aplicar melhores práticas críticas que previnem erros

Características:

• Tipo: "guardrail"
• Aplicação: "block"
• Prioridade: "critical" ou "high"
• Bloqueia edições de arquivo até que a habilidade seja usada
• Previne erros comuns (nomes de colunas, erros críticos)
• Ciente da sessão (não repete o aviso na mesma sessão)

Exemplos:

• database-verification - Verifica nomes de tabelas/colunas antes de consultas Prisma
• frontend-dev-guidelines - Aplica padrões React/TypeScript

Quando Usar:

• Erros que causam erros em tempo de execução
• Preocupações com integridade de dados
• Problemas críticos de compatibilidade

2. Habilidades de Domínio (Domain Skills)

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

Características:

• Tipo: "domain"
• Aplicação: "suggest"
• Prioridade: "high" ou "medium"
• Consultivo, 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 arquitetônicos
• Guias de como fazer

Início Rápido: Criando uma Nova Habilidade

Passo 1: Criar Arquivo de Habilidade

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

Modelo:

---
name: my-new-skill
description: Brief description including keywords that trigger this skill. Mention topics, file types, and use cases. Be explicit about trigger terms.
---

# My New Skill

## Purpose
What this skill helps with

## When to Use
Specific scenarios and conditions

## Key Information
The actual guidance, documentation, patterns, examples

Melhores Práticas:

• ✅ Nome: Minúsculas, hifens, forma gerúndio (verbo + -ing) preferível
• ✅ Descrição: Incluir TODAS as palavras-chave/frases de gatilho (máx. 1024 caracteres)
• ✅ Conteúdo: Menos de 500 linhas - usar arquivos de referência para detalhes
• ✅ Exemplos: Exemplos de código reais
• ✅ Estrutura: Títulos claros, listas, blocos de código

Passo 2: Adicionar ao skill-rules.json

Veja SKILL_RULES_REFERENCE.md para o esquema completo.

Modelo Básico:

{
  "my-new-skill": {
    "type": "domain",
    "enforcement": "suggest",
    "priority": "medium",
    "promptTriggers": {
      "keywords": ["keyword1", "keyword2"],
      "intentPatterns": ["(create|add).*?something"]
    }
  }
}

Passo 3: Testar Gatilhos

Testar UserPromptSubmit:

echo '{"session_id":"test","prompt":"your test prompt"}' | \

…