CommunityEscrita e Ediçãogithub.com

explicar

Explica como uma cadeia causal nas palavras do próprio usuário – problema primeiro, cada afirmação com seu porquê, em prosa técnica falada. Use quando o usuário perguntar por que ou como algo funciona ou falha, perguntar qual é o problema, disser que uma explicação não foi compreendida ou precisar entender a arquitetura de um sistema ou mudança.

O que é explicar?

Esta habilidade (skill) de agente de IA é projetada para gerar explicações técnicas que sejam claras, causais e centradas no vocabulário do usuário. Em vez de respostas genéricas, ela constrói uma 'cadeia causal' curta: cada afirmação carrega seu próprio porquê na mesma frase, usando exatamente os termos que o usuário já emprega. A habilidade é útil quando um desenvolvedor pergunta 'por que isso falhou?', 'como isso funciona?' ou quando uma explicação anterior não foi compreendida. Funciona em qualquer plataforma de agente que suporte skills (como Claude Code, Cursor, Codex) e segue um processo de três etapas: primeiro, coleta as palavras do usuário de sessões anteriores para identificar sua terminologia e lacunas; segundo, escreve a cadeia causal começando pelo problema e encadeando os porquês até um ponto de conhecimento compartilhado; terceiro, nomeia correções quando a terminologia ou suposições do usuário não correspondem ao código ou aos fatos. A saída é uma prosa falada de 3 a 5 frases, sem listas ou tabelas, ideal para leitura em voz alta.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NG-Bullseye/explain-skill/tree/main/skills/explain

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Uma explicação aqui é uma cadeia causal nas palavras do usuário: algumas frases curtas em que cada afirmação carrega sua razão, construída a partir dos termos com os quais o usuário já trabalha, lida de uma só vez, em voz alta se necessário.

1. Colete as palavras do usuário

A explicação se apega ao que o usuário sabe, e o que ele sabe se mostra nas palavras que digita. Antes de explicar um tópico pela primeira vez em uma sessão, leia como ele falou sobre ele:

python3 <pasta desta skill>/user_words.py <palavra-chave> [<palavra-chave> ...]
python3 <pasta desta skill>/user_words.py --all-projects <palavra-chave> ...

Isso imprime as mensagens que o usuário digitou em sessões anteriores do Claude que contêm uma palavra-chave, da mais nova para a mais antiga, para o projeto atual ou para todos. Escolha palavras-chave da pergunta dele e do tópico (nomes de componentes, ferramentas, a coisa que falha). Adicione as mensagens dele da conversa atual.

A partir disso, anote três coisas:

  • seus termos: a palavra que ele usa para cada coisa ("segundo caminho SSH", "IP de entrada", "proxied"). Use exatamente estas, mesmo onde o código ou a documentação as nomeiem de forma diferente.
  • terreno conhecido: o que ele afirmou ou usou corretamente. Uma cadeia pode terminar aí.
  • lacunas: termos do tópico que ele nunca usou. Cada um é uma palavra nova.

Feito quando cada termo que a explicação precisa está classificado como termo dele ou palavra nova.

2. Escreva a cadeia

  1. Problema primeiro. A primeira frase nomeia o problema ou a própria resposta: "O problema é X." Quando o usuário fez uma pergunta direta ("para que serve a senha?"), a primeira frase responde exatamente essa pergunta.
  2. Cada afirmação carrega seu porquê. Anexe a razão na mesma frase com porque / já que / devido a / por. Um efeito declarado sozinho é um elo solto: "todas as conexões vêm de 127.0.0.1" não explica nada até que "fail2ban bloqueia por IP" esteja ao lado.
  3. Encadeie até o terreno conhecido. Siga os porquês até que o último seja terreno conhecido. Pare aí.
  4. Termos dele, o mecanismo em si. Declare o mecanismo real literalmente, nos termos dele. Analogias, imagens e invenções estão descartadas.
  5. Palavras novas entre colchetes. Uma palavra nova aparece uma vez com palavras-chave entre colchetes logo atrás, depois sem: "HostKeyAlias (opção SSH: verifica a chave do host contra outra entrada em known_hosts)". Palavras-chave, não uma frase.
  6. Prosa falada. Três a cinco frases curtas declarativas, um elo por frase, na ordem causa para efeito. Texto corrido simples que sobrevive à conversão texto-para-fala: sem cabeçalhos, tabelas ou listas de marcadores dentro da explicação.

Para arquitetura, a cadeia percorre o caminho de uma requisição ou de uma mudança: qual parte age, o que ela entrega à próxima, por que a próxima pode ou não pode fazer seu trabalho com aquilo.

3. Nomeie as correções

A formulação e as suposições do usuário são verificadas contra o código e os fatos, e cada desvio é nomeado – depois da cadeia, uma linha cada, como "você diz … / o correto é … , porque …":

  • formulação que o código não suporta: ele diz "Passkey", é uma entrada do chaveiro; ele diz "Runner caiu", o runner é um contêiner e o Docker falhou. Dê o nome que o código ou a ferramenta usa, para que a próxima pergunta dele e o próximo resultado de busca dele acertem.
  • suposição errada: algo que ele toma como dado que não é verdade ("preciso da senha para a conexão"). Diga o que vale em vez disso e seu porquê.

Verifique contra o código ou o sistema antes de corrigir; uma correção vinda da memória é um palpite. Continue usando o termo dele depois apenas onde ele estava certo.

Modelo

A própria formulação da explicação que o usuário deveria ter recebido (por que o fail2ban não protege SSH atrás de um túnel Cloudflare). Os exemplos aqui estão em alemão; explique no idioma em que o usuário escreve.

O problema é o segundo caminho SSH por senha. Com nome de usuário e senha de usuário do Mac, qualquer pessoa pode fazer uma conexão por força bruta. fail2ban não protege, porque é bloqueio baseado em IP e, através do túnel, todo mundo tem o mesmo IP de entrada, já que Cloudflare faz proxy.

Feito quando

Antes de enviar, verifique cada frase:

  • a primeira frase nomeia o problema ou responde à pergunta feita;
  • cada afirmação tem seu porquê na mesma frase;
  • o último porquê é terreno conhecido para este usuário;
  • todo termo é termo dele, ou uma palavra nova com seu colchete;
  • toda formulação errada e suposição errada na pergunta dele é nomeada com sua correção.

Quando o usuário ainda não entender, encontre o elo cujo porquê está faltando e forneça apenas esse elo, em uma frase. Valores concretos (dois IPs, uma requisição) entram apenas aí, para fechar aquele elo.

O que fazer em seguida (opções, comandos, uma recomendação) vem depois da explicação, separado dela, e apenas quando solicitado ou necessário para agir.

Habilidades Relacionadas