Use CLAUDE.md para contexto geral do projeto. Use SKILL.md para processos reutilizáveis.
Essa é a diferença prática.
CLAUDE.md ajuda Claude a entender o ambiente onde está trabalhando. SKILL.md ensina Claude a executar uma tarefa específica quando ela aparece.
Resposta rápida
| Arquivo | Melhor uso |
|---|---|
CLAUDE.md |
Memória do projeto, comandos, padrões, estrutura, convenções e cuidados globais |
SKILL.md |
Checklist, playbook, rotina, workflow repetível e formato de entrega |
Se a informação precisa estar presente em quase toda sessão, use CLAUDE.md.
Se a instrução só importa quando uma tarefa específica aparece, use SKILL.md.
Outra forma de pensar:
CLAUDE.mdé orientação sempre presente;SKILL.mdé orientação carregada sob demanda.
Isso é o que evita transformar o contexto do projeto em um arquivo gigante cheio de procedimentos que só importam às vezes.
Exemplo simples:
| Situação | Melhor lugar |
|---|---|
| "Sempre rode testes antes de finalizar" | CLAUDE.md |
| "Como revisar um artigo antes de publicar" | SKILL.md |
| "Este projeto usa WordPress e Rank Math" | CLAUDE.md |
| "Checklist de FAQ schema e canonical" | SKILL.md |
| "Nunca expor credenciais" | CLAUDE.md |
| "Formato do relatório mensal para cliente" | SKILL.md |
O que é CLAUDE.md?
CLAUDE.md é um arquivo de memória do Claude Code.
Ele guarda informações que Claude deve considerar ao trabalhar naquele projeto, como:
- que projeto é este;
- como rodar build e testes;
- quais comandos são importantes;
- quais pastas importam;
- quais padrões seguir;
- quais cuidados existem;
- o que não mexer sem pedir;
- como lidar com ambiente, deploy ou publicação.
Pense nele como o mapa do projeto.
Exemplo seguro:
<pre><code>Projeto: blog WordPress com scripts locais de publicação.
Comandos úteis:
- Rodar QA público: python scripts/seo-aeo/qa_public_article.py
- Publicar artigo: python scripts/content-publishing/publish_markdown_article_pipeline.py
Cuidados:
- Criar backup antes de alterar post publicado.
- Nunca expor credenciais.
- Não reverter mudanças manuais sem confirmação.</code></pre>
Isso é contexto global. Claude pode precisar disso em muitas tarefas diferentes.
O que é SKILL.md?
SKILL.md é o arquivo principal de uma Claude Skill.
Ele contém metadados e instruções para uma capacidade específica.
Pense nele como o procedimento.
Exemplo seguro:
<pre><code>— name: publicar-artigo-blog description: Use quando o usuário pedir para publicar um artigo no blog WordPress.
Objetivo: Publicar um artigo com QA editorial, SEO e schema.
Processo:
- Revisar title, slug e meta description.
- Validar estrutura do artigo.
- Rodar pipeline de publicação.
- Aplicar FAQPage schema.
- Validar URL pública.
- Enviar IndexNow.
- Registrar na daily.</code></pre>
Esse checklist não precisa ficar carregado o tempo todo. Ele só importa quando a tarefa é publicar artigo.
A diferença real
A diferença não é "um arquivo é melhor que o outro".
A diferença é o tipo de conhecimento.
| Pergunta | Use |
|---|---|
| Claude precisa saber disso sempre? | CLAUDE.md |
| Isso é uma convenção do projeto? | CLAUDE.md |
| Isso é uma rotina específica? | SKILL.md |
| Isso tem checklist e formato de saída? | SKILL.md |
| Isso vale para muitas tarefas diferentes? | CLAUDE.md |
| Isso só vale quando eu pedir uma tarefa concreta? | SKILL.md |
Uma forma simples de decidir:
CLAUDE.md é contexto. SKILL.md é execução.
Quando usar CLAUDE.md
Use CLAUDE.md para regras e informações que devem acompanhar o projeto.
Bons exemplos:
- comandos de teste;
- comandos de build;
- arquitetura;
- stack;
- padrões de código;
- estrutura de pastas;
- regras de segurança;
- estilo editorial geral;
- fluxo de deploy;
- integrações críticas;
- decisões que não devem ser esquecidas.
Em um projeto de marketing, por exemplo, o CLAUDE.md pode dizer:
- qual é o tom da marca;
- quais produtos existem;
- quais CTAs são permitidos;
- qual pipeline publica conteúdo;
- quais páginas não devem ser alteradas sem cuidado;
- onde ficam dados de GSC, GA4 e relatórios.
Quando usar SKILL.md
Use SKILL.md quando existe uma rotina repetível.
Bons exemplos:
- revisar artigo antes de publicar;
- montar briefing SEO;
- criar relatório mensal;
- auditar campanha de Meta Ads;
- validar tracking;
- revisar landing page;
- fazer QA de PR;
- transformar call em plano de ação;
- criar roteiro de vídeo;
- preparar checklist de lançamento.
Uma Skill é boa quando você pensa:
"Toda vez que eu pedir isso, quero que Claude siga este processo."
Quando uma seção do CLAUDE.md deve virar Skill?
Quando ela cresce demais.
Sinais claros:
- a seção tem muitos passos;
- só vale para uma tarefa específica;
- tem checklist;
- tem exemplos;
- define formato de saída;
- ocupa espaço no contexto geral;
- você poderia chamar aquilo por nome.
Exemplo:
Se o CLAUDE.md tem uma seção enorme chamada "Como publicar artigo", com 25 passos, regras de FAQ, schema, capa, IndexNow e QA, isso provavelmente deveria virar uma Skill.
No CLAUDE.md, deixe só a referência:
<pre><code>Para publicar artigos, use a Skill publicar-artigo-blog.</code></pre>
E mova o procedimento completo para SKILL.md.
Quando não criar Skill
Nem tudo precisa virar Skill.
Não crie Skill quando:
- a regra vale sempre;
- a tarefa aconteceu uma vez;
- o processo ainda não está claro;
- a Skill ficaria genérica demais;
- você só quer guardar uma informação estática;
- o conteúdo muda toda semana e precisa de fonte viva.
Exemplo: "não expor credenciais" não deve ficar escondido em uma Skill. Isso é regra global.
Já "como validar uma publicação WordPress antes de fechar" é rotina específica. Aí sim faz sentido como Skill.
Como usar os dois juntos
O melhor setup normalmente usa os dois.
Exemplo para uma operação de conteúdo:
| Arquivo | Conteúdo |
|---|---|
CLAUDE.md |
Stack do projeto, comandos principais, regras de segurança, padrão editorial geral |
SKILL.md de briefing |
Como criar pauta com intenção, H2, FAQ e fontes |
SKILL.md de publicação |
Como publicar, aplicar schema, validar canonical e registrar na daily |
SKILL.md de atualização |
Como atualizar artigo antigo sem perder intenção e tráfego |
Assim, Claude entende o projeto sem carregar todos os checklists o tempo todo.
Estrutura prática
Uma organização possível:
<pre><code>CLAUDE.md .claude/ skills/ briefing-conteudo/ SKILL.md publicar-artigo/ SKILL.md qa-publicacao/ SKILL.md relatorio-cliente/ SKILL.md</code></pre>
O CLAUDE.md pode mencionar quais Skills existem, mas não precisa copiar o conteúdo delas.
Isso reduz duplicação e deixa cada arquivo com uma função clara.
Erros comuns
Colocar tudo no CLAUDE.md
Isso deixa o contexto pesado.
Claude passa a carregar instruções de publicação, relatório e QA mesmo quando você só quer discutir uma ideia rápida.
Criar Skill para contexto fixo
Se a regra importa sempre, não esconda em uma Skill.
Comandos essenciais, segurança e padrões globais devem ficar em CLAUDE.md.
Duplicar o mesmo checklist
Evite colocar o mesmo processo em CLAUDE.md e SKILL.md.
Escolha a fonte de verdade. Duplicação envelhece mal.
Criar Skill vaga demais
Uma Skill chamada marketing não ajuda muito.
Prefira nomes como:
briefing-conteudo;qa-publicacao;relatorio-cliente;auditar-meta-ads;revisar-copy-anuncio.
Esquecer de testar
Depois de criar uma Skill, teste se ela aciona na hora certa.
Se aciona demais, restrinja a descrição.
Se aciona pouco, deixe a descrição mais objetiva.
Matriz de decisão final
| Caso | Melhor escolha |
|---|---|
| Comando para rodar testes | CLAUDE.md |
| Procedimento de code review | SKILL.md |
| Estrutura do projeto | CLAUDE.md |
| Checklist de publicação | SKILL.md |
| Regra de segurança | CLAUDE.md |
| Modelo de relatório | SKILL.md |
| Tom geral da marca | CLAUDE.md |
| Checklist de copy para anúncio | SKILL.md |
| Onde ficam arquivos importantes | CLAUDE.md |
| Como executar uma rotina recorrente | SKILL.md |
Regra de bolso:
Se é memória do projeto, CLAUDE.md. Se é playbook de tarefa, SKILL.md.
Perguntas frequentes
CLAUDE.md e SKILL.md são a mesma coisa?
Não. CLAUDE.md guarda contexto geral do projeto. SKILL.md guarda instruções de uma Skill específica.
Quando usar CLAUDE.md?
Use CLAUDE.md para comandos, convenções, estrutura do projeto, regras globais, stack e contexto que Claude deve considerar com frequência.
Quando usar SKILL.md?
Use SKILL.md para processos repetíveis, checklists, rotinas e procedimentos que só importam em tarefas específicas.
Posso usar CLAUDE.md e SKILL.md juntos?
Sim. Em muitos projetos, CLAUDE.md orienta o contexto geral e Skills cuidam dos workflows específicos.
Uma Skill pode substituir parte do CLAUDE.md?
Sim. Quando uma seção do CLAUDE.md vira um procedimento longo e específico, ela pode ser movida para uma Skill.
O que não colocar em uma Skill?
Evite regras globais, credenciais, contexto que deve valer sempre e informações perecíveis que precisam ser buscadas em fonte atualizada.