Usando CLAUDE.md e Skills no Claude Code

Este artigo apresenta o que são o arquivo CLAUDE.md e o recurso Skills e faz uma comparação entre eles.

O Claude Code vai muito além de um simples assistente de código. Ele funciona como um agente que pode ser orientado, moldado e até “treinado” dentro do contexto do seu projeto. E dois conceitos são fundamentais para isso: o CLAUDE.md  e as Skills.

Se você entender esses dois elementos, você deixa de apenas usar IA — e passa a controlá-la de forma estratégica.

O que é o CLAUDE.md

O `CLAUDE.md` é um arquivo que fica dentro do seu projeto e define as regras permanentes que o Claude deve seguir.

Ele funciona como um guia de comportamento baseado no contexto do projeto.

Quando você executa o Claude Code dentro de uma pasta, ele automaticamente:

1. Procura um arquivo `CLAUDE.md`
2. Lê seu conteúdo
3. Usa essas instruções como base para todas as respostas

Ou seja: O Claude passa a entender “como pensar” dentro daquele projeto

Exemplo real (.NET + EF Core)

# Regras do projeto - Usar EF Core com boas práticas - Evitar N+1 - Sempre usar async/await - Não usar repository genérico - Preferir projeção com Select - Usar AsNoTracking para leitura

Para que serve o CLAUDE.md

Ele serve para definir as regras e o contexto do seu projeto para a IA e garantir que o Claude trabalhe do jeito certo dentro do seu projeto como por exemplo:

- Padronizar código
- Evitar decisões erradas da IA
- Garantir consistência arquitetural
- Reduzir retrabalho
- Alinhar IA com o time/projeto

O `CLAUDE.md` não é só um arquivo técnico. Ele é, na prática uma forma de documentar e impor arquitetura através da IA

O que são Skills

As Skills no Claude Code são pastas contendo instruções, scripts e recursos que o Claude carrega dinamicamente para automatizar tarefas repetitivas e especializadas. Elas funcionam como "habilidades" ou "agentes" que transformam a IA em um desenvolvedor sênior, seguindo padrões específicos, usando ferramentas externas e ativando-se automaticamente com base no contexto do projeto.

UPara criar uma skill você pode criar uma pasta para a skill em sua pasta de skills pessoais. As Skills pessoais estão disponíveis em todos os seus projetos.

mkdir -p ~/.claude/skills/minha-skill

A seguir crie um arquivo SKILL.md dentro da pasta minha-skill.

 Cada skill precisa de um arquivo SKILL.md com duas partes:

1- frontmatter YAML (entre marcadores ---) que diz ao Claude quando usar a skill,

2- Conteúdo markdown com instruções que Claude segue quando a skill é invocada. O campo name se torna o /slash-command, e o  campo  description ajuda o Claude a decidir quando carregá-la automaticamente.

Exemplo:

Você pode testá-la de duas formas:

1- Deixe Claude invocá-la automaticamente perguntando algo que corresponda à descrição:
 Como isso funciona ?

2- Invocando a skill diretamente com o nome da skill:  /explicar-codigo src/auth/login.cs

Uma Skill define:
   Como o Claude deve responder
   Qual nível de profundidade usar
   Qual papel assumir

Exemplo de Skill na plataforma .NET para adicionar CRUD em uma API:

--- name: adicionar-crud description: Gera endpoints CRUD (GET, GET/id, POST, PUT, DELETE) para uma entidade usando Minimal APIs. argument-hint: "<nomeEntidade>" disable-model-invocation: false --- O usuário pediu para criar endpoints CRUD para a entidade `$0`. Siga estas regras: 1. Use Minimal API com `MapGroup` para agrupar os endpoints sob `/api/$0s` (plural minúsculo). 2. Implemente os 5 endpoints padrão: - GET / → retorna todos (async, `ToListAsync`) - GET /{id} → retorna um ou 404 - POST / → adiciona, retorna 201 com location - PUT /{id} → atualiza todos os campos, retorna 204 ou 404 - DELETE /{id} → remove, retorna 204 ou 404 3. Use os tipos corretos: `AppDbContext`, `$0`, `Results<T>` ou `IResult`. 4. Adicione os usings necessários no topo do `Program.cs` se não existirem. 5. Coloque o código dos endpoints **imediatamente após** `var app = builder.Build();` e antes de `app.Run();`.

Uso típico : /skill adicionar-crud

Após ativar as skills, todas as respostas seguem esse comportamento automaticamente.

Para que servem Skills

As Skills servem para controlar como a IA pensa e executa uma tarefa. Não é sobre o que ela sabe é sobre como ela usa esse conhecimento. Assim elas são usadas para:

- Evitar repetir instruções
- Especializar a IA para tarefas específicas
- Aumentar profundidade técnica
- Criar “personas técnicas”

As Skills são, essencialmente prompts estruturados reutilizáveis com identidade

Comparação: CLAUDE.md vs Skills

Agora vamos ao ponto mais importante: entender a diferença real entre os dois.

Diferença conceitual

O CLAUDE.md não muda o comportamento diretamente, ele limita e orienta o espaço de decisão enquanto que uma Skill não define regras do projeto, ela define a forma de atuação dentro dessas regras

Assim CLAUDE.md → define o 'mundo'  e a Skill define o “papel dentro do mundo'

Exemplo combinado (muito importante)

### CLAUDE.md - Usar EF Core corretamente - Evitar N+1 - Preferir Select ### Skill ativa Você é um especialista em desempenho com EF Core.

Resultado:  O Claude respeita as regras do projeto e atua com profundidade técnica

Como usar isso no mundo real

Aqui está o uso profissional desses dois conceitos:

1. CLAUDE.md (base sólida)

Use para definir:
  Arquitetura
  Padrões de código
  Regras obrigatórias
  Boas práticas

Isso evita que a IA “invente moda”

2. Skills (especialização)

Use para:
  Revisão de código
  Análise de desempenho
  Geração de conteúdo
  Debug

Isso aumenta a qualidade da resposta

Estratégia ideal

Sempre combine os dois: CLAUDE.md → estabilidade e Skill → flexibilidade

Erros comuns (e como evitar)

1- Não usar CLAUDE.md
Resultado:
  IA inconsistente
  Código desalinhado

2- Colocar tudo em prompt manual
Resultado:
  Retrabalho constante
  Baixa produtividade

3- Skills genéricas
Resultado:
   Respostas superficiais

Uso Correto
  CLAUDE.md bem definido
  Skills específicas
  Prompts objetivos

Conclusão

O verdadeiro poder do Claude Code não está apenas em gerar código — mas em ser configurado corretamente com contexto e especificações.

O `CLAUDE.md` funciona como a base estrutural que garante consistência e alinhamento com o projeto.

As Skills atuam como camadas de especialização, permitindo que a IA assuma papéis específicos e execute tarefas com maior profundidade.

Quando usados juntos, eles transformam o Claude de um simples assistente em algo muito mais poderoso em um agente técnico alinhado ao seu projeto e adaptado ao seu fluxo de trabalho

Se você dominar esses dois conceitos, você deixa de “pedir ajuda para IA” e passa a orquestrar comportamento inteligente dentro do seu ambiente de desenvolvimento

E isso é exatamente o que diferencia uso básico de uso profissional de IA.

E estamos conversados...  

"Portanto, agora nenhuma condenação há para os que estão em Cristo Jesus, que não andam segundo a carne, mas segundo o Espírito."
Romanos 8:1