O que você não deve colocar dentro de uma skill de marketing?

Abre a sua skill de marketing agora e lê ela com olhos de estranho: o que esse arquivo entrega de graça?

Ele parece um documento interno, mas não é

SKILL.md é arquivo de texto puro, vai pro git junto com o resto do projeto e ainda ocupa a janela de contexto do modelo quando a skill é ativada

Neste post eu listo o que nunca deveria ser gravado ali dentro (dado pessoal de cliente, credencial, informação sensível de campanha e cláusula de contrato) e, mais importante, mostro como entregar exatamente o mesmo contexto pro modelo sem deixar nada disso guardado no arquivo

Bora? 🙂

Por que uma skill compartilhada é um arquivo de risco

Antes da régua, o motivo dela

Um estudo empírico em larga escala analisou 31.132 skills únicas de dois grandes marketplaces e encontrou 26,1% com pelo menos uma vulnerabilidade, distribuídas em 14 padrões distintos

Os dois campeões: exfiltração de dados (13,3%) e escalação de privilégio (11,8%)

Outro estudo, esse focado só em vazamento de credencial, olhou 17.022 skills e achou 520 delas (3,1%) com 1.708 ocorrências de segredo exposto

Se liga no detalhe que dói: 84,0% dos casos foram por descuido do próprio desenvolvedor, e 89,6% das skills afetadas eram exploráveis durante execução rotineira, sem privilégio elevado

Ou seja: não precisa de invasor genial, precisa só de alguém rodando a skill do jeito normal

A Snyk foi por outro caminho e varreu 3.984 skills do ClawHub e do skills.sh no estudo ToxicSkills: 36,82% tinham ao menos uma falha de segurança e 13,4% tinham problema de nível crítico, num total de 534 skills com pelo menos um item crítico, incluindo distribuição de malware, injeção de prompt e segredos expostos

E não é só papo de pesquisador: a própria Anthropic pede cuidado especial ao integrar skills em sistemas de produção com acesso a dados sensíveis ou operações críticas

Marketing é exatamente esse terreno, né? base de cliente, verba, contrato, número que não pode circular

Antes de escrever: entenda onde a sua skill vai parar

O porquê antes do como: o risco nasce do formato do arquivo

Uma skill é uma PASTA, não um arquivo solto

Dentro dela mora o SKILL.md, que combina metadados estruturados em frontmatter YAML (delimitado por ---) com instruções livres em Markdown, e a pasta ainda pode trazer references/, scripts/ e assets/, como descreve a documentação de Agent Skills

No frontmatter, só dois campos são obrigatórios: name e description

E a description é o que faz o agente decidir se carrega a skill, então ela é a vitrine da coisa

---
name: campanha-email
description: Escreve variacoes de e-mail de campanha seguindo o tom e a estrutura padrao da marca
---

Agora a parte que muita gente pula

No Claude Code, as skills vivem em duas pastas: ~/.claude/skills para skills pessoais e .claude/skills dentro do repositório para skills de projeto, que são compartilhadas pelo time via git

"Compartilhada via git" significa: quem tem o repo tem o arquivo, agora e no histórico

Tem ainda um terceiro caminho, a distribuição por marketplace de plugins: o usuário roda /plugin marketplace add usuario-ou-org/repo e instala pelo menu /plugin, sendo o marketplace um repositório git com um arquivo .claude-plugin/marketplace.json

E vale a lembrança geral: a pasta .claude do projeto e ~/.claude no diretório do usuário são as origens de skills e configurações do Claude Code (CLAUDE.md, settings.json, hooks, commands, subagents, memória automática e por aí vai)

Juntando tudo, a régua fica óbvia: o que você escreve ali é auditável por qualquer pessoa com acesso ao repositório

O que tirar da skill, passo a passo (e o que colocar no lugar)

Quanto mais focada a tarefa, menos contexto sensível a skill precisa carregar, então vale decidir antes quais tarefas delegar ao agente e só depois escrever o arquivo

1. Dado pessoal de cliente: troque por placeholder e descreva o formato

O trecho ruim é aquele exemplo "real" que alguém colou pra ilustrar:

Exemplo de lead: Ana Ribeiro, [email protected], telefone (11) 9....

A versão saneada:

Formato do lead: {{nome}}, {{email}}, {{telefone}}
Use o primeiro nome do lead na saudacao
Se o telefone estiver vazio, siga sem ele

O erro comum deste passo: achar que um contato verdadeiro é inofensivo porque é "só um cliente". O modelo não precisa do dado real pra entender o formato, ele precisa do formato

2. Credencial e token: referência, nunca o valor

Esse é o trecho ruim clássico:

Para puxar as metricas da conta, use a API com a chave sk-live-...

A versão saneada não guarda valor nenhum:

A chave da API de metricas vem do ambiente
O valor nao e escrito neste arquivo em nenhuma hipotese

E onde o valor mora? No Claude Code, variáveis de ambiente podem ser declaradas na chave env de um arquivo settings.json, e o Claude Code as lê direto do arquivo, independentemente de como a sessão foi iniciada

Pra configuração de servidor MCP, a documentação orienta usar referência a variável de ambiente no lugar do segredo: a referência é lida do ambiente do shell quando o Claude Code sobe o servidor, então o token nunca fica gravado no arquivo de configuração

Se o segredo vale só pra um projeto, tem o .claude/settings.local.json

O erro comum deste passo: criar esse arquivo na mão e commitar junto. Quando o próprio Claude Code salva uma configuração ali, ele adiciona o arquivo ao gitignore global; se foi você quem criou, a documentação orienta adicionar ao gitignore ANTES, pra não commitar a credencial por acidente

Tome cuidado: uma vez que o segredo entrou no commit, ele não deixa de existir só porque você apagou a linha depois

3. Informação sensível de campanha: guarde o método, não o número

O corpo do SKILL.md deve descrever COMO decidir, não QUANTO é

Ruim: a skill traz a verba fechada do trimestre e o CPA teto da conta
Bom: toda proposta de midia respeita o CPA teto vigente, informado na conversa

O erro comum deste passo: colar o número "pra facilitar". Além de virar dado exposto no repo, ele envelhece e a skill passa a orientar decisão com base em valor velho

4. Cláusula de contrato: descreva a restrição em linguagem de regra

Nada de colar parágrafo de contrato ou de NDA dentro do arquivo

Ruim: colar o texto integral da clausula de exclusividade do cliente
Bom: nao citar concorrentes do cliente em nenhuma peca, sem excecao

O erro comum deste passo: confundir a fonte com a regra. O contrato continua no jurídico, a skill fica só com a instrução que sai dele

5. Scripts da pasta scripts/: corte o log de depuração

Esse aqui é o mais subestimado de todos

A exposição por log de depuração (print e console.log) responde por 73,5% das ocorrências de vazamento de credencial, porque os frameworks de agente capturam a saída padrão dentro da janela de contexto do modelo

Resultado: a credencial logada fica recuperável por pergunta em linguagem natural, sem esforço nenhum

# ruim
print(f"DEBUG usando token: {api_token}")

# bom
print("DEBUG token carregado do ambiente")

O erro comum deste passo: deixar o print que "era só pra testar". Ele não é só seu, ele vira contexto do modelo

6. Revise a pasta inteira antes de publicar

A auditoria recomendada pela Anthropic cobre todos os arquivos empacotados na skill: SKILL.md, os markdowns referenciados, scripts, imagens e demais recursos

O que você procura: chamadas de rede inesperadas, padrões de acesso a arquivos e operações que não batem com o propósito declarado

O guia de skills para empresas vai além e manda ler todo o conteúdo do diretório verificando se não há padrões de exfiltração, ou seja, instruções que leiam dados sensíveis e depois gravem, enviem ou codifiquem esses dados para transmissão externa

A mesma orientação fecha com a régua que resume o post: instalar uma skill deve ser tratado com o mesmo rigor de instalar software em produção

O erro comum deste passo: revisar só o SKILL.md e ignorar scripts/ e assets/, que é justamente onde as coisas se escondem

Onde cada informação deve ficar em vez do SKILL.md

Consulta rápida pra quando bater a dúvida no meio da escrita:

Três situações em que o dado sensível entra sem ninguém perceber

Ninguém acorda pensando "hoje vou vazar a base de leads", a coisa entra de lado

A skill pessoal que virou skill de projeto. Ela nasceu em ~/.claude/skills, sozinha na sua máquina, com um exemplo real aqui e um token ali. Aí ela funcionou bem, alguém copiou pra .claude/skills do repositório e pronto: o que era pessoal virou compartilhado com o time via git. Antes de mover, releia o arquivo linha a linha como se fosse a primeira vez

O exemplo de campanha colado "só pra ilustrar". O caso real deixa a instrução mais clara, é verdade, e é por isso que ele entra. Só que ele carrega cliente, número e contexto que não deveriam viajar. Troque o caso real por um caso genérico com a mesma estrutura: o modelo aprende o padrão do mesmo jeito

A skill de terceiro instalada por marketplace. Aqui o risco inverte de direção: em vez de você vazar algo, a skill é que pode agir fora do propósito declarado. A documentação recomenda usar skills apenas de fontes confiáveis (criadas por você mesmo ou obtidas da Anthropic), porque uma skill maliciosa pode instruir o Claude a acionar ferramentas ou executar código fora do que ela promete. Vale entender direitinho o que você realmente baixa antes de rodar qualquer coisa vinda de fora

E tem um bônus que não é de segurança, mas ajuda: o Claude lê o SKILL.md apenas quando a skill se torna relevante, e lê os arquivos adicionais só conforme a necessidade

Quando a skill ativa, cada token do corpo disputa espaço com o histórico da conversa e com os outros arquivos de contexto

Ou seja: cortar o que não é essencial deixa a skill mais segura E mais eficiente, os dois no mesmo movimento 😀

Conclusão

A régua que resolve quase toda dúvida é essa: se o texto perde valor ao ser lido por um estranho, ele não pertence ao SKILL.md

Dado pessoal de cliente sai e vira placeholder de formato

Credencial sai e vira referência a variável de ambiente

Número fechado de campanha sai e vira critério

Cláusula de contrato sai e vira regra

Próximo passo é hoje mesmo: abre as suas skills de marketing, roda a revisão arquivo por arquivo (SKILL.md, markdowns referenciados, scripts/ e assets/) e move cada segredo pro ambiente antes do próximo commit

É meia hora de trabalho que evita um problema que os números do começo do post mostram ser bem mais comum do que parece…

até o próximo post!