🔧 Dicas Técnicas

Rodar a frio é um teste onde você abre o Claude Code e digita um prompt vago, sem citar o nome da skill ou dar qualquer pista sobre qual ferramenta deve ser acionada.

É a forma mais honesta de validar se a skill foi bem construída. Se ela dispara quando deveria, o gatilho está calibrado. Se não dispara, você sabe exatamente onde ajustar.

Prompt vago, gatilho implícito, teste de disparo, validação real.

Quando você dá pistas explícitas ao modelo ("use a skill X"), qualquer skill dispara. Prompts vagos forçam o modelo a inferir qual ferramenta usar com base nos metadados da skill.

O usuário real não vai dizer "use a skill de copywriting". Ele vai dizer "escreve um post pra mim". A skill precisa ser forte o suficiente para ser reconhecida nesses casos.

Inferência de contexto, sinal vs. ruído, qualidade dos metadados, relevância semântica.

Abra uma nova sessão, formule um prompt que descreva o problema sem nomear a solução, envie e observe qual skill (se alguma) o Claude escolhe usar.

O processo é simples mas exige disciplina. É fácil inconscientemente formular o prompt de forma que induz o modelo. Aprender a ser neutro é a habilidade central.

Nova sessão limpa, prompt neutro, observação do comportamento, registro do resultado.

Skill dispara = gatilho bem calibrado. Skill não dispara = descrição fraca ou ausência de palavras-chave relevantes. Skill errada dispara = conflito entre descrições de skills similares.

Cada resultado aponta para uma ação específica. Não é apenas "funcionou ou não" — é um diagnóstico preciso que te diz exatamente o que melhorar.

Três estados possíveis: disparo correto, sem disparo, disparo errado. Cada um tem solução diferente.

Quando uma skill incorreta é acionada, o problema geralmente está em descrições muito genéricas ou sobreposição de vocabulário entre duas skills diferentes da sua biblioteca.

Ter a skill errada disparar pode ser pior que não disparar nenhuma — você recebe output incorreto sem perceber que está errado. Identificar e corrigir conflitos é crítico.

Conflito de vocabulário, diferenciação semântica, especificidade da descrição, teste comparativo.

Os 5 pontos: sessão limpa, prompt neutro sem dicas, skill correta disparou, output corresponde ao esperado, ausência de conflito com outras skills.

Um checklist transforma o teste subjetivo em protocolo objetivo. Você sabe exatamente o que verificar e não precisa confiar na memória.

5 pontos: sessão limpa, neutralidade do prompt, disparo correto, qualidade do output, ausência de conflito.

O Claude Code não lê a descrição inteira da skill. Existe um limite de tokens que faz com que descrições longas sejam truncadas antes de chegarem ao context window do modelo.

Se você colocar informações críticas no final da descrição, elas podem nunca ser lidas. Entender esse limite muda radicalmente como você estrutura suas skills.

Truncamento, limite de tokens, context window, prioridade da informação.

Na prática, o modelo recebe apenas os primeiros caracteres da descrição quando está decidindo qual skill usar. O restante pode existir, mas não influencia a decisão de disparo.

Saber o que o modelo vê versus o que você escreveu é fundamental. Muitas skills falham porque foram escritas para humanos lerem, não para o modelo inferir.

Visão do modelo, seleção de ferramenta, tokens de descrição, inferência de uso.

A primeira frase da descrição deve conter explicitamente quando e por que usar a skill. "Use quando X", "Acione para Y", "Dispara quando Z" são formatos que funcionam.

Com o gatilho no início, mesmo que o modelo leia apenas os primeiros tokens, ele já tem a informação essencial para decidir se deve ou não acionar a skill.

Primeira frase, gatilho explícito, "Use quando", posicionamento estratégico, informação crítica first.

Descrição enxuta não é descrição vaga. É remover o óbvio, eliminar o redundante e manter apenas o que diferencia a skill e define seu gatilho de uso.

Cada palavra desperdiçada em redundância é uma palavra que poderia conter mais contexto útil. A concisão aqui é uma estratégia técnica, não um estilo.

Densidade de informação, eliminação de redundância, especificidade, economia de tokens.

Você pode pedir ao Claude para descrever o que sabe sobre suas skills disponíveis. A resposta revela o que ele realmente recebeu, expondo qualquer truncamento.

Sem esse teste, você está escrevendo às cegas. Ver o que o modelo recebeu fecha o loop e confirma se sua descrição está chegando completa.

Inspeção de metadados, confirmação de recepção, diagnóstico de truncamento, iteração informada.

Comparação direta entre descrições mal posicionadas (gatilho no final, muito vagas ou muito longas) e descrições otimizadas com gatilho no início e linguagem densa.

Exemplos concretos aceleram o aprendizado. Ver o antes e depois faz o padrão ficar gravado — você reconhece uma boa descrição imediatamente após ver essa comparação.

Padrão ruim vs. padrão bom, reconhecimento visual, aplicação imediata, biblioteca de exemplos.

O loop morto é quando a skill gera um output, o usuário acha genérico, pede refinamento, recebe outro output genérico, e assim por diante sem nunca chegar no resultado correto.

Reconhecer o loop morto é o primeiro passo para quebrá-lo. A solução não é mais iteração — é coletar o contexto certo antes de começar a gerar.

Loop morto, contexto insuficiente, output genérico, iteração ineficiente, quebra de ciclo.

O Ask User Input Tool é a primitiva nativa do Claude Code que pausa a execução da skill e faz uma pergunta direta ao usuário, aguardando a resposta antes de continuar.

Dominar essa ferramenta permite criar skills que são essencialmente entrevistadores — coletam exatamente o que precisam e só então entregam o resultado personalizado.

Ask User Input, pausa de execução, coleta de contexto, personalização dinâmica, output direcionado.

Nem toda skill precisa de entrevista. Skills de copywriting, análise de negócio, planejamento estratégico e geração de conteúdo personalizado são as que mais se beneficiam.

Usar entrevista onde não é necessário cria fricção desnecessária. Saber distinguir quando a entrevista agrega versus quando atrasa é uma habilidade de design de skill.

Skills de alto contexto, variabilidade de entrada, personalização necessária, fricção vs. valor.

As perguntas de maior impacto são sobre público-alvo, contexto de uso, tom desejado e restrições. Perguntas sobre preferências cosméticas têm menor impacto que perguntas sobre contexto.

Com o número certo de perguntas (geralmente 2-4), você maximiza a qualidade do output sem sobrecarregar o usuário. Mais perguntas não significa melhor resultado.

Perguntas de alto impacto, economia de interação, público, contexto, tom, restrições.

A entrevista pode ser linear (perguntas fixas em sequência) ou adaptativa (pergunta seguinte depende da resposta anterior). Skills simples usam linear; skills complexas se beneficiam do modelo adaptativo.

Estruturar a entrevista corretamente garante que você colete o contexto na ordem certa, sem redundância e sem deixar lacunas que comprometeriam o output.

Entrevista linear, entrevista adaptativa, sequência de perguntas, dependência condicional, cobertura de contexto.

Uma skill de copywriting que usa Ask User Input para coletar produto, público-alvo, plataforma e tom antes de gerar o copy — resultando em saídas consistentemente mais precisas.

Ver o exemplo completo fecha o ciclo teórico e te dá um template funcional para adaptar nas suas próprias skills. É o passo da compreensão para a implementação.

Template completo, Ask User Input em ação, 4 perguntas essenciais, output personalizado, aplicação direta.

O Claude tem padrões de escrita treinados que afloram quando não há instruções específicas: frases evasivas, concordâncias excessivas, uso de m-dash estilístico, linguagem de relatório corporativo.

Sem regras explícitas de voz, o output vai soar como "Claude escrevendo", não como "você escrevendo". Regras de tom são a diferença entre copy genérico e copy autêntico.

Padrões default do modelo, autenticidade de voz, regras explícitas vs. implícitas, copy genérico vs. personalizado.

Sycophancy em LLMs é o comportamento de concordar excessivamente, elogiar de forma vazia e evitar contradições. "Ótima pergunta!", "Absolutamente!", "Com certeza!" são exemplos clássicos.

Essas frases destroem a credibilidade do copy. Ninguém acredita em conteúdo que parece escrito para agradar. Anti-sycophancy é uma das regras mais impactantes que você pode adicionar.

Sycophancy, frases proibidas, autenticidade, credibilidade, regras de proibição explícita.

O m-dash (—) é usado com frequência exagerada pelo Claude como substituto de vírgulas e dois-pontos. Além disso, o modelo tende a usar "Além disso", "Portanto", "No entanto" em excesso.

Esses padrões são marcadores visíveis de "texto gerado por IA". Proibi-los explicitamente na skill cria textos que parecem escritos por um humano com voz própria.

M-dash, conectores de transição em excesso, marcadores de IA, humanização do texto, lista de proibições.

Tonalidade vai além de "formal" ou "informal". É a combinação de ritmo de frase, vocabulário preferido, nível de jargão técnico, uso de humor e grau de assertividade.

Definir tonalidade com exemplos reais (frases do próprio usuário) é mais eficaz que descrições abstratas. "Direto, sem rodeios, usa gírias do setor" é melhor que "casual".

Definição por exemplo, ritmo de frase, vocabulário específico, assertividade, consistência de voz.

Regras reais como: "Nunca comece frases com 'Além disso'", "Use parágrafos curtos de até 3 linhas", "Prefira verbos ativos a passivos", "Evite adjetivos vagos como 'incrível' ou 'transformador'".

Regras concretas são executáveis. O modelo sabe exatamente o que fazer ou não fazer. Quanto mais específica e mensurável a regra, melhor o resultado.

Regras concretas vs. abstratas, executabilidade, especificidade, biblioteca de regras de voz.

As regras de tom devem estar em uma seção dedicada, preferencialmente antes das instruções de conteúdo. A posição afeta a atenção do modelo — regras no início recebem mais peso.

A mesma regra em lugares diferentes pode ter impactos diferentes. Colocar as regras de tom no início da skill garante que sejam aplicadas consistentemente em todo o output.

Posicionamento estratégico, peso de instrução, seção dedicada, hierarquia de regras, início vs. fim.

Um feedback loop é um mecanismo onde cada uso da skill gera informação sobre sua performance. Sem esse loop, a skill pode degradar silenciosamente sem que você perceba.

Skills que nunca são avaliadas ficam estagnadas. O feedback loop transforma o uso cotidiano em processo de melhoria contínua sem esforço adicional significativo.

Feedback loop, avaliação contínua, melhoria iterativa, degradação silenciosa, dados de uso.

Ao final de cada execução, a skill pergunta: "De 1 a 10, qual nota você dá para este output?" — simples, rápido, sem fricção. A nota é registrada e usada para iteração.

A escala 1-10 é universalmente compreendida e gera dados comparáveis. Uma pergunta simples ao final da sessão basta para criar um histórico valioso de performance.

Escala 1-10, pergunta ao final, baixa fricção, dados comparáveis, histórico de performance.

Após a nota, a skill faz uma segunda pergunta: "O que faltou para ser 10?" — essa pergunta direciona o usuário a articular exatamente o gap entre o output recebido e o output ideal.

A nota sozinha não informa o que melhorar. O "porquê não foi 10" é que revela o gap real — e esse gap é o insumo direto para a próxima iteração da skill.

Gap de qualidade, articulação do usuário, insumo para iteração, segunda pergunta, diagnóstico do déficit.

Notas abaixo de 7 são sinais para revisão imediata. Notas 7-8 indicam ajustes pontuais. Notas 9-10 confirmam que a skill está calibrada — mas ainda merecem ser analisadas para padrões.

Sem um protocolo de ação, as notas acumulam sem gerar mudança. Definir thresholds de ação transforma dados em melhoria real da skill.

Thresholds de ação, revisão imediata, ajustes pontuais, confirmação de calibração, protocolo de resposta.

O rating vai na seção final da skill, após todas as instruções de output. Deve ser uma seção separada com o texto exato das duas perguntas e instrução para registrar a resposta do usuário.

A posição e o formato da integração determinam se o rating será efetivamente executado. Uma seção mal posicionada ou ambígua será ignorada ou executada inconsistentemente.

Seção final, duas perguntas obrigatórias, registro da resposta, instrução clara, posição estratégica.

Uma skill completa com a seção de rating integrada ao final — mostrando o texto exato das perguntas, como registrar e como usar a informação na próxima revisão da skill.

Ver o template completo permite replicar a estrutura diretamente. Você não precisa inventar — só adaptar o padrão comprovado para suas skills existentes.

Template de rating, seção final padronizada, texto das perguntas, replicabilidade, aplicação imediata.

Reverse meta prompting é a prática de mostrar o arquivo da skill ao Claude e pedir que ele a analise criticamente como se fosse um engenheiro de prompts experiente, identificando pontos fracos e propondo melhorias.

O Claude tem conhecimento profundo sobre o que faz um prompt funcionar. Usar esse conhecimento para melhorar suas próprias skills é um atalho poderoso que a maioria ignora completamente.

Meta análise, autocrítica assistida, engenheiro de prompts, visão externa, melhoria guiada.

A maioria das pessoas cria a skill, usa uma ou duas vezes, e nunca mais a revisa. A ausência de revisão crítica é o maior bloqueador de performance de uma biblioteca de skills.

Entender por que esse passo é tão ignorado (falta de protocolo, conforto com o "bom o suficiente") ajuda a criar o hábito consciente de revisão crítica periódica.

Inércia de revisão, zona de conforto, hábito de melhoria, protocolo de iteração, consciência do gap.

O prompt padrão é: "Você é um engenheiro de prompts sênior. Analise esta skill e responda: quais são os 3 maiores problemas? Como você a reescreveria para maximizar a consistência do output?"

O formato do prompt de reflexão determina a qualidade da análise. Um prompt genérico gera análise genérica. Um prompt estruturado gera diagnóstico preciso e acionável.

Prompt de reflexão padrão, roleplay de especialista, diagnóstico estruturado, 3 problemas, proposta de reescrita.

Depois da análise, o Claude vai propor mudanças. Interpretar o diff significa entender o que mudou, por que mudou e se a mudança alinha com sua intenção original para a skill.

Aceitar cegamente todas as mudanças pode desvirtuar a skill. Você precisa ser o árbitro final — o Claude propõe, você decide o que faz sentido para seu contexto.

Leitura de diff, aprovação seletiva, alinhamento com intenção, autonomia do usuário, filtro humano.

Uma skill melhorada 1% por dia está 37x melhor em um ano. O efeito composto da iteração constante torna skills mediocres em ferramentas excepcionais ao longo do tempo.

O conceito de melhoria incremental remove a pressão de fazer revisões dramáticas. Uma pequena melhoria consistente supera uma grande revisão esporádica.

Efeito composto, melhoria incremental, consistência vs. intensidade, 37x em 1 ano, hábito de iteração.

Uma transcrição comentada de uma sessão real: skill original → prompt de reflexão → análise do Claude → aprovação seletiva das mudanças → skill evoluída.

Ver o processo completo de ponta a ponta remove a ambiguidade de como fazer. Você sai da sessão sabendo exatamente o que fazer com suas próprias skills.

Sessão completa, before/after, análise comentada, aprovação seletiva, template replicável.

Usar skill para tudo cria uma biblioteca inflada onde a maioria das skills é subutilizada, conflita com outras ou poderia ser substituída por uma primitiva mais simples e eficaz.

Menos skills bem calibradas superam muitas skills mal posicionadas. Saber quando não usar skill é tão importante quanto saber como criá-la.

Biblioteca inflada, skills subutilizadas, conflito de primitivas, minimalismo eficaz, escolha consciente.

Rules são instruções que o Claude sempre segue, independente do contexto. São ideais para comportamentos consistentes e globais — como formatação, idioma ou proibições permanentes.

Uma rule "sempre responda em português" é mais eficaz que uma skill que instrui o mesmo. Rules têm prioridade maior e menor overhead de ativação.

Regra determinística, comportamento global, prioridade alta, menor overhead, quando usar rule vs. skill.

O CLAUDE.md carrega contexto persistente sobre o projeto, o usuário e preferências globais. É ideal para informações que devem estar sempre disponíveis sem precisar de ativação.

Colocar contexto de projeto em CLAUDE.md ao invés de em skills evita redundância e garante que o contexto esteja disponível em qualquer interação, não apenas quando a skill é ativada.

Contexto persistente, disponibilidade global, sem ativação, projeto vs. tarefa, CLAUDE.md como base.

Para tarefas determinísticas e repetíveis sem variabilidade de contexto, um script ou alias de linha de comando é mais rápido, mais confiável e mais simples que uma skill.

Skills têm overhead de interpretação. Para tarefas mecânicas, esse overhead não vale o custo. Reconhecer quando a CLI é superior economiza tempo e evita complexidade desnecessária.

Overhead de interpretação, tarefa determinística, alias de CLI, eficiência, quando CLI supera skill.

Quando um processo se repete com as mesmas entradas e saídas esperadas, uma automação (n8n, Make, script Python) é superior a uma skill que precisa ser ativada manualmente.

Automatizar o que é repetível libera a skill para o que requer julgamento e adaptação contextual — o único domínio onde a skill tem vantagem real sobre outros mecanismos.

Processo repetível, automação vs. julgamento, n8n/Make, ativação manual vs. automática, especialização de ferramenta.

Um fluxo de decisão com 4 perguntas: É sempre verdadeiro? → Rule. É contexto persistente? → CLAUDE.md. É determinístico e repetível? → CLI/Automação. Requer julgamento contextual? → Skill.

Com o fluxo memorizado, a decisão leva 30 segundos em vez de 30 minutos. Você para de criar skills por inércia e começa a escolher a primitiva certa conscientemente.

4 perguntas decisivas, fluxo de 30 segundos, escolha consciente, primitiva certa, eliminação de inércia.

Com o tempo, skills acumulam instruções conflitantes, seções obsoletas e gatilhos desatualizados. Uma biblioteca não auditada é como uma codebase sem testes — funciona até parar de funcionar.

Auditoria proativa é mais eficiente que debug reativo. Identificar problemas antes que causem outputs errados economiza muito mais tempo do que investigar por que uma skill parou de funcionar.

Degradação acumulada, auditoria proativa, conflito de instruções, seções obsoletas, saúde da biblioteca.

O claude-code-guide é um agente pré-configurado com conhecimento profundo sobre estrutura de skills, boas práticas de prompting e padrões de qualidade do Claude Code SDK.

Usar um agente especializado é mais eficaz que pedir ao Claude genérico para auditar. O agente tem critérios específicos e consistentes que tornam a auditoria comparável entre diferentes skills.

Agente especializado, critérios consistentes, auditoria comparável, claude-code-guide, conhecimento de SDK.

O prompt de auditoria padrão solicita: análise de estrutura (seções presentes/ausentes), qualidade do gatilho, clareza das instruções, conflitos internos e score de qualidade 0-100.

Um prompt de auditoria bem estruturado gera relatórios acionáveis. Você sai da auditoria com uma lista ordenada de problemas, não com uma crítica subjetiva sem direção.

Análise estrutural, score de qualidade, lista de problemas ordenada, relatório acionável, critérios objetivos.

O checklist inclui: descrição tem gatilho no início, seções obrigatórias presentes, sem instruções conflitantes, exemplos de input/output, seção de avaliação, sem dead code.

Conhecer os critérios do checklist permite que você os aplique manualmente também. A auditoria pelo agente é mais rápida, mas entender os critérios melhora a qualidade das skills que você cria.

6 pontos do checklist, gatilho, seções obrigatórias, sem conflitos, exemplos, avaliação, sem dead code.

Priorizar por impacto: skills com score abaixo de 60 primeiro, depois as mais utilizadas, depois as que têm conflito com outras. Corrija na ordem de maior impacto no seu workflow.

Sem priorização, você pode gastar tempo em skills raramente usadas enquanto as mais críticas permanecem problemáticas. Priorizar bem maximiza o retorno da auditoria.

Priorização por impacto, score threshold, skills críticas, ordem de correção, retorno da auditoria.

A cadência recomendada é: auditoria completa trimestral, revisão rápida das skills mais usadas mensalmente e correção imediata sempre que uma skill gerar output abaixo de 7.

Uma cadência definida transforma auditoria de tarefa ad hoc em hábito de manutenção. A biblioteca se mantém saudável sem exigir esforço concentrado em momentos de crise.

Cadência trimestral, revisão mensal, correção imediata, manutenção preventiva, hábito de qualidade.