Como dar contexto de negócio para a sua skill de marketing no Claude Code?

Fala aí, beleza? Sua skill de marketing não escreve texto genérico por falta de capacidade

ela escreve genérico porque ninguém contou pra ela o que é o produto, quem compra e o que a pessoa responde antes de comprar

E dá pra entender o porquê olhando como a coisa funciona por baixo. Uma skill, na base, é uma pasta com um arquivo SKILL.md dentro, e esse arquivo precisa começar com um frontmatter YAML com dois campos obrigatórios: name e description

O carregamento é por divulgação progressiva. Na inicialização o agente pré-carrega apenas o name e a description de cada skill instalada, e o corpo do SKILL.md só é lido quando a skill é considerada relevante pra tarefa

Traduzindo: o contexto de negócio precisa estar escrito em algum lugar que o agente ALCANCE na hora certa

Se não estiver, o modelo preenche o buraco com a média da internet, e média da internet é exatamente aquele texto morno que você já leu em mil landing pages 😀

Bora resolver isso?

O que você precisa ter em mãos antes de escrever o contexto

Tem duas frentes aqui, e elas são bem diferentes. Uma é chata e rápida, a outra é a que dá trabalho de verdade

O lado técnico:

• Uma skill válida: pasta + SKILL.md com frontmatter YAML contendo name e description
• name com até 64 caracteres, só letras minúsculas, números e hífens
• description com até 1.024 caracteres
• Saber onde ela mora no Claude Code: ~/.claude/skills/ para skill pessoal e .claude/skills/ dentro do repositório para skill de projeto
• Opcional: um pacote pronto pra usar de base, em vez de começar do zero

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

O opcional aí vale a pena. Existe um pacote público de skills de marketing pro Claude Code no repositório coreyhaines31/marketingskills, cobrindo CRO, copywriting, SEO, analytics e growth engineering

A instalação é pelo marketplace de plugins:

/plugin marketplace add coreyhaines31/marketingskills
/plugin install marketing-skills

Repara numa pegadinha aí: o repositório se chama marketingskills, tudo junto, e o plugin que você instala se chama marketing-skills, com hífen. São duas coisas diferentes mesmo (o endereço do repo e o nome do plugin dentro do marketplace), então copia exatamente do jeito que está

E antes de sair escrevendo a sua, vale a pena garimpar skills prontas que já resolvem metade do caminho

O lado do negócio:

Essa parte ninguém instala por você, é a informação que só você tem. O pacote citado organiza isso num documento de contexto que cobre:

• Visão geral do produto: frase única, categoria e modelo de negócio
• Público-alvo e personas
• Problemas e dores
• Cenário competitivo: concorrentes diretos, secundários e indiretos
• Diferenciação
• Objeções e antipersonas
• Dinâmica de troca: push, pull, hábito e ansiedade
• Linguagem do cliente, com frases literais
• Voz e tom da marca
• Provas e depoimentos
• Metas de negócio

Se liga que quase nada disso é técnico. É trabalho de marketing mesmo, só que escrito num arquivo em vez de ficar na cabeça de três pessoas da empresa

Como dar contexto de negócio para a skill, passo a passo

Vamos por partes, e em cada passo eu marco o erro comum, porque é sempre o mesmo erro que estraga o resultado

1. Decida onde o contexto mora

Se você tem várias skills de marketing, o contexto NÃO deve viver dentro de cada SKILL.md. Ele vira um arquivo compartilhado que todas leem

No pacote citado, todas as skills leem de .agents/product-marketing.md, onde produto, público e posicionamento são definidos uma vez só

Detalhe de migração: na versão 2.0 esse arquivo saiu de .claude/ para .agents/ e foi renomeado de product-marketing-context.md para product-marketing.md, mas as skills ainda checam a pasta e o nome antigos como fallback

O erro comum deste passo: colar o mesmo bloco de empresa dentro de cinco skills e depois ter que atualizar em cinco lugares quando o posicionamento muda

2. Escreva a visão geral do produto em uma frase, categoria e modelo de negócio

Uma frase. Categoria. Como entra dinheiro. Só isso

O erro comum deste passo: começar pela história da empresa, aquele "fundada em 2019 com a missão de transformar". Isso não ajuda a skill a escrever nada, ocupa espaço e some no meio do arquivo

3. Descreva público, persona e a dor em palavras do cliente

Aqui entra a parte que a maioria pula: as frases literais

Anota como o cliente descreve o problema quando fala sozinho, no suporte, no comentário, na call. Não a versão traduzida pro marketês

O erro comum deste passo: descrever o público por cargo e faixa etária e ignorar COMO ele fala. Cargo não escreve headline, vocabulário escreve

4. Registre objeções e antipersonas

O que trava a compra, e quem não é cliente

Antipersona é ouro aqui, porque ensina a skill a não puxar um público que não converte

O erro comum deste passo: listar só benefício. Aí a skill escreve uma peça animadinha que nunca encosta no motivo real de a pessoa não comprar

5. Registre concorrência, diferenciação, provas e metas de negócio

Concorrentes diretos, secundários e indiretos, o que te diferencia de cada um, os depoimentos que você pode usar e o que o negócio persegue

O erro comum deste passo: diferencial vago tipo "somos mais simples". Isso não sobrevive a uma página de comparação, e a skill vai gerar uma tabela que perde da concorrência sozinha

6. Enxugue o arquivo

A recomendação oficial de autoria é manter o SKILL.md com menos de 500 linhas e mover material detalhado para arquivos de apoio, como uma pasta references/, lidos sob demanda

A estrutura fica mais ou menos assim:

.claude/skills/
  copy-vendas/
    SKILL.md          <- curto, instrução de como escrever
    references/
      objecoes.md     <- detalhe, lido sob demanda
      depoimentos.md
.agents/
  product-marketing.md  <- contexto compartilhado

E já que a gente está falando de jogar informação de negócio dentro de arquivo que uma ferramenta de IA vai ler, vale o mesmo cuidado que a gente discute quando o assunto é privacidade dos seus dados no NotebookLM: contexto útil sim, dado sensível de cliente não

O erro comum deste passo: transformar a skill em manual da empresa. Manual completo não é contexto, é ruído com sumário

7. Corte o que o modelo já sabe

As boas práticas oficiais são bem diretas: adicione apenas o contexto que o Claude ainda não tem

Explicar o que é uma landing page é desperdício. Explicar que o SEU público chega na landing page já tendo testado dois concorrentes, isso sim é contexto

A mesma orientação diz pra evitar blocos de ALWAYS, NEVER e MUST em caixa alta, porque regra rígida erra caso de borda e se aplica demais onde caberia julgamento

O erro comum deste passo: encher o arquivo de proibição em caixa alta achando que assim a IA obedece mais. Ela obedece até no caso em que obedecer é burrice

8. Ajuste a description pra dizer o que a skill faz E quando usar

Lembra que a description é o que fica pré-carregado? Ela é o texto contra o qual o pedido do usuário é comparado pra decidir se aciona a skill

Exemplo de frontmatter:

---
name: copy-vendas
description: Escreve e revisa copy de pagina de vendas e e-mail usando o contexto de negocio compartilhado do produto. Use quando o pedido envolver landing page, e-mail de lancamento, anuncio ou headline.
---

O erro comum deste passo: description bonita e vaga, tipo "ajuda com marketing". A skill fica lá, linda, e nunca aciona 😛

9. Use o atalho do rascunho automático, mas revise

A skill de contexto desse pacote tem um modo de rascunho automático: ela lê o repositório (README, landing pages, textos de marketing, páginas sobre, meta descriptions, package.json), produz uma primeira versão do documento e pede que você revise, corrija e preencha as lacunas

É MUITO mais fácil corrigir uma V1 do que encarar o arquivo em branco

O erro comum deste passo: aceitar o rascunho como está. Ele foi montado a partir do que já estava escrito no repo, então ele repete o seu posicionamento genérico atual com cara de documento oficial

Que informação de negócio muda o quê no texto que sai

Nem todo contexto serve pra tudo. Cada tipo de informação muda uma entrega específica, e enxergar isso ajuda a decidir o que escrever primeiro

Vai item por item:

Objeções e antipersonas: página de vendas e e-mail passam a responder o que trava a compra, em vez de empilhar benefício

Linguagem literal do cliente: título e chamada saem com o vocabulário de quem compra, não com o do time interno

Diferenciação e cenário competitivo: a página de comparação para de ser tabela genérica e passa a defender uma posição

Voz e tom da marca: o social deixa de soar como post institucional de qualquer empresa

Metas de negócio: a skill persegue a métrica certa em vez de otimizar o que for mais fácil

Dinâmica de troca (push, pull, hábito, ansiedade): o texto ataca o momento da decisão, não só o produto

Olhando assim fica fácil escolher por onde começar: escreve primeiro o que muda a entrega que você mais precisa hoje

E tem um efeito colateral bom no arranjo de arquivo compartilhado: no pacote citado, as skills de CRO, copywriting, SEO, analytics e growth engineering leem do MESMO arquivo

Ajustou o posicionamento uma vez, reflete em todas

É como trocar a variável de config num projeto, em vez de sair caçando string hardcoded em dez lugares

Conclusão

O gargalo da sua skill de marketing é contexto, não prompt

Não existe frase mágica que faça o modelo adivinhar sua objeção número 1 de venda, seu concorrente indireto e o jeito que seu cliente descreve a dor dele

Próximo passo concreto: escreve HOJE a versão 1 do documento de contexto, mesmo curta, mesmo torta

Produto em uma frase, persona, três dores, três objeções, dois concorrentes, voz

Aponta a skill pra esse arquivo e vai corrigindo conforme o texto sai errado. É assim que ele fica bom, não na primeira sentada

E tem uma boa notícia sobre esse esforço não ser jogado fora: as Agent Skills foram anunciadas pela Anthropic em 16 de outubro de 2025 e, em 18 de dezembro de 2025, a especificação foi publicada como padrão aberto em agentskills.io

Ou seja: o formato do SKILL.md não é regra só do Claude Code, virou especificação aberta. Uma skill escrita numa ferramenta roda em qualquer plataforma que suporte o padrão, já que na base é só uma pasta com um SKILL.md

Seu documento de contexto acompanha você em qualquer agente compatível, e isso muda o cálculo do tempo que você investe nele =)

até o próximo post!