Skill de marketing: o que colocar além do texto de instrução para a entrega não sair rasa

Fala aí, beleza? Tu escreveu um SKILL.md de umas 30 linhas, chamou a skill, e o que voltou foi um texto genérico, daqueles que qualquer prompt solto entregaria

Aí bate a dúvida: será que a instrução ficou vaga demais?

Na maior parte das vezes o problema não é a instrução

Se liga nisso: uma Agent Skill não é um arquivo, é uma PASTA. O SKILL.md é o único obrigatório, e ao redor dele existem três diretórios opcionais: scripts/, references/ e assets/

E é justamente nesses opcionais que mora o padrão da entrega: modelo de estrutura, checklist de revisão, exemplo de peça pronta no formato que tu espera

Sem isso, o agente tem a ordem mas não tem a régua…

O que você precisa antes de montar a estrutura

Onde a skill vai morar:

No Claude Code as skills são baseadas em sistema de arquivos, e existem dois níveis de pasta:

• ~/.claude/skills/ para as skills pessoais
• .claude/skills/ dentro do projeto, para as skills daquele projeto

A escolha aqui não é detalhe. Skill pessoal te acompanha em tudo, skill de projeto fica onde o contexto dela faz sentido

E se tu quer reusar as mesmas skills em todos os projetos, vale pensar nisso antes de sair criando pasta em qualquer canto

Tome cuidado com nome repetido! Quando duas skills têm o mesmo nome, existe uma ordem de precedência por origem: enterprise sobrepõe pessoal, e pessoal sobrepõe projeto

Ou seja: tu pode ter uma versão no projeto e ela simplesmente nunca rodar, porque a pessoal ganhou 😅

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

Os dois campos obrigatórios do frontmatter:

O frontmatter YAML do SKILL.md tem só dois campos obrigatórios: name e description

Os opcionais permitidos são license, allowed-tools, metadata e compatibility

E a especificação define limites de tamanho e formato. Repara que a última linha da tabela é de um campo OPCIONAL, ela entra aqui só porque também tem limite definido:

Um esqueleto de skill de marketing começa mais ou menos assim:

---
name: skill-de-marketing
description: Cria e revisa peças de marketing seguindo o guia de marca, o tom de voz e os modelos de estrutura da empresa. Use quando o pedido envolver escrever, adaptar ou revisar material de comunicação da marca.
---

Repara que a description já diz o que faz E em qual situação usar. Já já explico o porquê disso 🙂

Passo a passo: montando a skill de marketing com material de apoio

1. Gere o esqueleto em vez de criar tudo na mão

O repositório anthropics/skills traz a skill skill-creator, que guia a criação de skills e o planejamento dos recursos de apoio

Dentro dela tem um script que cria o diretório da skill, gera um SKILL.md com frontmatter e placeholders TODO, e já cria as pastas scripts/, references/ e assets/ com arquivos de exemplo:

scripts/init_skill.py <skill-name> --path <output-directory>

O erro comum deste passo: começar escrevendo o corpo do SKILL.md num arquivo solto e só depois pensar em onde guardar o resto. Aí o material de apoio nunca nasce, porque não tem lugar pra ele

2. Escreva a description pensando no acionamento, não na explicação

name e description são os únicos campos que o agente enxerga antes de acionar a skill

Então o "quando usar" pertence à description

O erro comum deste passo: criar uma seção "Quando usar esta skill" no corpo do SKILL.md. Não ajuda no acionamento, porque o corpo só é lido DEPOIS que a skill disparou

É como colocar a placa do restaurante dentro da cozinha: quem tá na rua nunca vai ver

3. Deixe o corpo do SKILL.md enxuto

A doc oficial de boas práticas recomenda alvo de 1.500 a 2.000 palavras no corpo, com o conteúdo detalhado empurrado para references/

No caso de uma skill de marketing, o corpo fica com o fluxo (o que fazer, em que ordem, o que checar antes de entregar)

O guia de marca completo, a documentação de produto, a tabela de personas: tudo isso vai pra references/

O erro comum deste passo: achar que texto longo é sinônimo de instrução forte. Não é. Corpo inchado só empurra ruído pro contexto

4. Coloque os modelos e os exemplos em assets/

Cada pasta opcional tem um papel definido: scripts/ guarda código executável que o agente roda, references/ guarda documentação carregada em contexto quando necessário, e assets/ guarda modelos, arquivos de template e binários

Os arquivos além do SKILL.md servem justamente pra isso: templates pro Claude preencher, exemplos de saída no formato esperado, scripts executáveis e documentação de referência detalhada

Aqui mora a virada de qualidade. Um exemplo de peça pronta ensina o formato MUITO mais rápido que três parágrafos descrevendo o formato

O erro comum deste passo: descrever a estrutura da peça em prosa dentro do corpo, em vez de entregar o modelo pronto pra preencher

5. Referencie cada arquivo a partir do SKILL.md

Esse é o passo que quase todo mundo pula

Os arquivos de apoio só são lidos se o SKILL.md os referenciar, explicando o que contêm e quando carregar

## Material de apoio

- `references/guia-de-marca.md`: cores, tom de voz e termos proibidos.
  Abra antes de escrever qualquer peça pública.
- `assets/modelo-landing.md`: estrutura de seções da landing page.
  Preencha este modelo em vez de inventar a estrutura.
- `assets/exemplo-email-lancamento.md`: exemplo de saída no formato esperado.
  Consulte quando o pedido for e-mail.

O erro comum deste passo: arquivo órfão. Tu escreve um checklist de revisão lindo em references/, e ele nunca é aberto porque nada no corpo diz que ele existe e quando usar

6. Empacote a skill

O skill-creator também traz um script de empacotamento, o scripts/package_skill.py, que exclui do pacote diretórios como __pycache__ e node_modules, além de arquivos .pyc e .DS_Store

O erro comum deste passo: mandar a pasta inteira zipada na mão, com lixo de execução junto

E, pra distribuir, no Claude Code os plugins são o formato de distribuição e podem empacotar uma ou mais skills. A marketplace da Anthropic entra assim:

/plugin marketplace add anthropics/skills

No Agent SDK a lógica é parecida: as skills em .claude/skills/ são descobertas automaticamente quando settingSources inclui "project", e dá pra restringir ferramentas pelo parâmetro allowedTools

Que material de apoio faz diferença numa skill de marketing

Beleza, mas o que exatamente colocar em cada pasta quando o assunto é marketing?

E tem um molde real pra olhar antes de inventar o teu

A skill brand-guidelines, do repositório oficial, carrega o sistema de cores e a hierarquia tipográfica da marca e aplica isso em artifacts: slides, documentos, relatórios e páginas HTML

Ou seja, ela não pede pro agente "seguir a identidade visual" e torce pelo melhor. Ela CARREGA a identidade e aplica

É exatamente esse o pulo do gato

Se tu tá começando agora, vale dar uma olhada no repositório oficial de skills antes de copiar estrutura de qualquer repo aleatório

O que muda na prática quando a skill tem apoio

O carregamento das skills acontece em três níveis (o tal do progressive disclosure):

• nível 1: só name e description de todas as skills ficam pré-carregados
• nível 2: o corpo do SKILL.md é lido quando a skill se torna relevante
• nível 3: os arquivos de apoio são lidos só quando necessários

Sacou por que o SKILL.md gigante é um mau negócio? Ele entra inteiro no nível 2, útil ou não

Enquanto isso, a skill bem montada só puxa o guia de marca quando a peça é pública, e só abre o exemplo de e-mail quando o pedido é e-mail

No vídeo abaixo eu mostro isso rodando de verdade, com uma skill de pesquisa que instalei no Claude Code

Instalei pelo fluxo de plugin (adicionei o marketplace primeiro e depois o plugin daquele marketplace), e escolhi de propósito instalar só na pasta do projeto em vez de global, pra não poluir a lista de skills e não acionar sem querer em outro lugar

Depois de instalar, precisei rodar o reload de plugins antes dela ficar disponível

Quando testei, a pesquisa completa levou quase 5 minutos na minha máquina, e ela foi mostrando o passo a passo: começou pela busca web e depois foi reportando o retorno de vários agentes, separando os achados por fonte

O resultado veio em inglês, porque eu não pedi idioma nenhum. Só saiu em português quando escrevi isso junto do prompt 😅

E aí veio a parte que mais casa com o assunto deste post: depois da pesquisa, em vez de ler o documento inteiro, eu fiz perguntas em português sobre o arquivo gerado, e ela respondeu usando o material que já tinha salvo

Teve também a flag que gera o documento em HTML: demorou mais que a saída em markdown, porque precisava montar o documento, mas ficou bem mais visual

Depois pedi pra enriquecer esse HTML com dados, tabelas comparativas e recursos visuais, e o documento voltou bem mais completo que a primeira versão

Moral: o material de apoio não é enfeite, é o que a ferramenta consulta quando precisa

Próximo passo

Se a tua skill de marketing entrega texto raso, antes de reescrever a instrução pela quinta vez, olha o que falta em volta dela

Na maioria dos casos não falta ordem, falta padrão: modelo de estrutura, exemplo de peça pronta, guia de marca acessível e um SKILL.md enxuto que diga qual arquivo abrir e quando

O próximo passo é bem direto: roda o skill-creator do repositório anthropics/skills pra gerar o esqueleto com scripts/, references/ e assets/ já criados

Depois escolhe UMA peça que tu produz toda semana e coloca o modelo dela em assets/

Faça o teste e compara a saída antes e depois. A diferença aparece já na primeira rodada 😀

até o próximo post!