A Diferença Crucial Entre .agents e .claude no Desenvolvimento de AI Agents
Nota do Autor: Este artigo detalha as diferenças de posicionamento entre as pastas de configuração .agents e .claude no desenvolvimento de AI Agents, as convenções para armazenamento de Skills, uma comparação das estruturas de diretórios e os cenários de aplicação de AGENTS.md e CLAUDE.md.
O desenvolvimento de AI Agents está cada vez mais popular, e é comum vermos diversas pastas de configuração na raiz do projeto – .agents, .claude, .cursor, etc. Dentre elas, .agents e .claude podem ambas armazenar Skills, mas seus posicionamentos, filosofias de design e escopos de aplicação são completamente diferentes. Escolher o local errado para armazenar seus Skills pode, na melhor das hipóteses, fazer com que eles não funcionem, e na pior, causar conflitos de configuração durante a colaboração em equipe. Este artigo irá aprofundar nas diferenças centrais e nas melhores práticas, partindo do design de baixo nível.
Valor Central: Após ler este artigo, você terá clareza sobre se deve colocar seus Skills em .agents ou .claude, e como gerenciar eficientemente as configurações do Agent em equipes com múltiplas ferramentas.
Pontos-chave das pastas .agents e .claude
Vamos direto ao ponto principal: essas duas pastas não são concorrentes, mas sim sistemas de configuração em diferentes níveis.
| Dimensão de Comparação | Pasta .claude/ |
Pasta .agents/ |
|---|---|---|
| Pertencente a | Anthropic (Exclusivo do Claude Code) | Fundação Agentic AI / Fundação Linux |
| Posicionamento | Diretório de configuração de projeto do Claude Code | Padrão de configuração de Agente independente de ferramenta |
| Formato de Skills | SKILL.md (Metadados YAML + Markdown) |
SKILL.yaml (YAML puro) |
| Maturidade | Pronto para produção, suporte oficial do Claude Code | Norma em desenvolvimento (Work In Progress) |
| Suporte Multi-ferramenta | Apenas Claude Code | Projetado para todas as ferramentas de Agente de IA |
Diferenças na filosofia de design entre as pastas .agents e .claude
A diferença fundamental entre essas duas pastas reside em suas filosofias de design:
A pasta .claude/ segue a abordagem de "integração profunda e exclusiva". Ela é feita sob medida para o Claude Code, oferecendo funcionalidades completas de Skills, Subagents, Hooks, Permissions, etc., profundamente ligadas à cadeia de ferramentas do Claude Code. A vantagem é a funcionalidade completa e a facilidade de uso; o custo é o aprisionamento no ecossistema do Claude Code.
A pasta .agents/ segue a abordagem de "padrão universal multi-ferramenta". Ela tenta definir uma especificação de configuração que todas as ferramentas de Agente de IA possam entender, semelhante ao .editorconfig para editores. A vantagem é que uma única configuração pode ser usada em várias ferramentas; o custo é que a especificação ainda está em evolução e o suporte das ferramentas varia.
Ambas podem coexistir perfeitamente no mesmo projeto — configurações profundas exclusivas do Claude Code vão para .claude/, e configurações universais reutilizáveis vão para .agents/.
Estrutura de diretório completa da pasta .claude
Vamos primeiro dar uma olhada na pasta nativa .claude/ do Claude Code, que é a implementação mais madura atualmente.
Detalhamento da estrutura de diretório da pasta .claude
.claude/
├── CLAUDE.md # Instruções do projeto (substitui CLAUDE.md na raiz)
├── settings.json # Configurações do projeto (enviadas para o git, compartilhadas pela equipe)
├── settings.local.json # Configurações locais (gitignore, configuração pessoal)
├── skills/ # Diretório de habilidades (Skills)
│ └── <nome-da-skill>/
│ ├── SKILL.md # Arquivo de definição da habilidade (obrigatório)
│ ├── scripts/ # Scripts auxiliares
│ ├── references/ # Materiais de referência
│ └── templates/ # Arquivos de modelo
├── agents/ # Definições de subagentes
│ └── <nome-do-agente>.md # Arquivo de definição do subagente
├── commands/ # Comandos de barra da versão antiga (mesclados em skills)
│ └── <nome-do-comando>.md
└── agent-memory/ # Memória persistente do subagente
└── <nome-do-agente>/
└── MEMORY.md
Além disso, existe o diretório de nível de usuário ~/.claude/, onde as Skills pessoais podem ser colocadas para que funcionem em todos os projetos:
~/.claude/
├── CLAUDE.md # Instruções de nível de usuário (entre projetos)
├── settings.json # Configurações de nível de usuário
├── skills/ # Skills pessoais (disponíveis em todos os projetos)
├── agents/ # Subagentes pessoais
└── projects/ # Histórico e dados de sessão
Formato SKILL.md para Skills na pasta .claude
As Skills do Claude Code são definidas usando arquivos Markdown com metadados YAML no cabeçalho:
---
name: minha-skill
description: Descrição da habilidade, ajuda o Claude a decidir quando acionar
user-invocable: true # O usuário pode chamar via /minha-skill
allowed-tools: Read, Grep # Limita as ferramentas disponíveis
context: fork # Executa em um subagente independente
model: sonnet # Cobertura do modelo
---
Você é um assistente profissional de revisão de código...
(Instruções da habilidade em formato Markdown)
Explicação dos campos chave:
- Skills com
user-invocable: truesão registradas como/comandos-de-barra context: forksignifica que a execução ocorre em um contexto independente, sem poluir a conversa principalallowed-toolspode restringir o conjunto de ferramentas que uma Skill pode usar- Suporte para substituição de parâmetros como
$ARGUMENTS,$0,$1
🎯 Recomendação de desenvolvimento: O sistema de Skills do Claude Code segue o padrão aberto Agent Skills (agentskills.io), e a sintaxe é universal entre Claude Code, Claude API e VS Code Copilot.
Se você estiver desenvolvendo aplicações de IA com Claude Code, recomendamos obter sua chave API através da APIYI apiyi.com para gerenciar invocações de múltiplos modelos de forma unificada.
Estrutura Completa de Diretórios do .agents
A especificação do diretório .agents/ (AGENTS-1 Spec) é mantida pela Agentic AI Foundation, sob a Linux Foundation, com o objetivo de definir um padrão de configuração universal que todas as ferramentas de codificação de IA possam entender.
Detalhes da Estrutura de Diretórios do .agents
.agents/
├── manifest.yaml # Obrigatório: Configura o registro, declara todas as configurações disponíveis
├── prompts/ # Obrigatório: Instruções de prompt
│ ├── base.md # Instruções genéricas do Agent
│ ├── project.md # Instruções específicas do projeto
│ └── snippets/ # Pedaços de instruções modulares
├── modes/ # Obrigatório: Modos de comportamento (semelhante a .claude/agents/)
│ ├── plan.md # Modo de planejamento
│ ├── code.md # Modo de codificação
│ └── review.md # Modo de revisão
├── policies/ # Obrigatório: Políticas de segurança e restrições de capacidade
├── skills/ # Obrigatório: Definições de habilidades (seguindo a especificação Agent Skills)
│ └── <name>/
│ └── SKILL.yaml # Definição de habilidade em formato YAML
├── scopes/ # Obrigatório: Substituições em nível de caminho (suporte a Monorepo)
├── profiles/ # Obrigatório: Sobreposições de configuração nomeadas (dev/ci/staging)
├── schemas/ # Obrigatório: Validação JSON Schema
└── state/ # Estado local (não enviar para git)
├── .gitignore
└── state.yaml
Ao contrário das Skills do .claude/ que usam SKILL.md (Markdown), as Skills do .agents/ usam o formato SKILL.yaml (YAML puro).
Design Único do Diretório .agents
A especificação .agents/ possui vários conceitos que não existem no .claude/:
- Scopes (Escopos): Define configurações diferentes para subdiretórios distintos em um Monorepo, com o caminho mais específico tendo prioridade na correspondência.
- Profiles (Perfis): Suporta sobreposições de configuração nomeadas como
dev,ci,prod, etc., semelhante a variáveis de ambiente. - Policies (Políticas): Um diretório independente de restrições de segurança, onde regras de negação sempre têm precedência sobre regras de permissão.
- Determinism (Determinismo): Entradas idênticas devem produzir saídas idênticas, sem depender de estado externo.
Comparação das Regras de Armazenamento de Skills nos Diretórios .agents e .claude
Esta é a questão prática mais preocupante para os desenvolvedores: onde exatamente devo colocar minhas Skills?
Comparativo de Skills nos Diretórios .agents e .claude
| Dimensão de Comparação | .claude/skills/ |
.agents/skills/ |
|---|---|---|
| Arquivo de Definição | SKILL.md (Markdown + YAML frontmatter) |
SKILL.yaml (YAML puro) |
| Suporte Claude Code | Suporte nativo, descoberta automática | Requer configuração manual ou aguardar suporte oficial |
| Comando de Barra | user-invocable: true registra automaticamente /command |
Depende da implementação específica da ferramenta |
| Execução de Sub-agente | context: fork executa em um contexto independente |
Configurado através de modes/ |
| Substituição de Modelo | model: sonnet especifica diretamente |
Configurado através de profiles/ |
| Restrições de Ferramenta | allowed-tools: Read, Grep |
Através de policies/ |
| Arquivos Auxiliares | Subdiretórios scripts/, references/, templates/ |
Depende da implementação |
| Passagem de Parâmetros | Substituição de variáveis $ARGUMENTS, $0, $1 |
A especificação não define claramente |
Como os Diretórios .agents e .claude Podem Coexistir
Em projetos reais, os dois diretórios podem coexistir e se complementar. No exemplo deste projeto:
.claude/skills/ armazena skills exclusivas do Claude Code:
apiyi-article-generator— Geração de artigos, com integração profunda de modelos e padrões do projeto.apiyi-svg-generator— Geração de ilustrações SVG, dependente de modelos SVG do projeto.apiyi-content-reviewer— Revisão de conteúdo, utilizando os padrões de qualidade do projeto.
.agents/skills/ armazena skills genéricas e portáteis:
markdown-proxy— Captura de URL para Markdown, utilizando script Python.nano-banana-pro-image-gen— Geração de imagens, chamando APIs externas.
O princípio de divisão é claro: coloque no .claude/ o que é profundamente integrado ao Claude Code, e no .agents/ o que pode ser reutilizado em outras ferramentas de IA.
🎯 Sugestão de Escolha: Se sua equipe usa apenas o Claude Code, coloque tudo em
.claude/skills/para ter a funcionalidade mais completa.
Se os membros da equipe usam diferentes ferramentas de IA (Cursor, Windsurf, Codex, etc.), colocar skills genéricas em.agents/skills/facilita a colaboração.
Para chamadas de API em desenvolvimento de Agentes de IA, recomendamos o gerenciamento unificado através da APIYI apiyi.com, com uma única chave API cobrindo múltiplos modelos.
Comparativo de Arquivos de Instrução .agents e .claude
Além da pasta Skills, ambos os sistemas possuem seus próprios arquivos de instrução de projeto.
Diferenças entre CLAUDE.md e AGENTS.md
| Dimensão de Comparação | CLAUDE.md | AGENTS.md |
|---|---|---|
| Ferramentas Suportadas | Claude Code | Claude Code, OpenAI Codex, Google Jules, Cursor, GitHub Copilot, etc. |
| Nível de Arquivo | Nível de usuário (~/.claude/) → Nível de projeto (./) → Nível de subdiretório |
Nível de projeto (./) → Nível de subdiretório |
| Sobrescrita Local | CLAUDE.local.md (gitignore) |
Nenhum |
| Norma Formal | Nenhum (documentação do produto Anthropic) | Sim (Agentic AI Foundation sob a Linux Foundation) |
| Escala do Ecossistema | Em crescimento (adotado por Next.js, LangChain, Deno, etc.) | Grande escala (n8n 178K estrelas, llama.cpp 97K estrelas, Bun 82K estrelas) |
| Inicialização | Comando /init dentro do Claude Code |
Criação manual |
Recomendação Prática: Ambos os arquivos podem coexistir. CLAUDE.md pode conter instruções exclusivas para o Claude Code (como configurações de Hooks, regras de permissão), enquanto AGENTS.md pode conter o contexto do projeto comum a todas as ferramentas de IA (como comandos de build, convenções de codificação, descrições de arquitetura).
Visão Geral do Ecossistema de Arquivos Complementares .agents e .claude
| Arquivo/Diretório | Sistema Pertencente | Propósito | Enviado para git |
|---|---|---|---|
CLAUDE.md |
.claude | Instruções de projeto do Claude Code | Sim |
CLAUDE.local.md |
.claude | Instruções locais pessoais | Não |
.claude/settings.json |
.claude | Permissões, Hooks, MCP | Sim |
.claude/settings.local.json |
.claude | Configurações locais pessoais | Não |
AGENTS.md |
.agents | Instruções de projeto genéricas do Agent | Sim |
.agents/manifest.yaml |
.agents | Registro de configuração | Sim |
.agents/state/state.yaml |
.agents | Estado de execução local | Não |
.cursorrules |
Cursor | Regras exclusivas do Cursor | Sim |
Dica: Uma pesquisa de 2026 da ETH Zurich indicou que arquivos de contexto gerados por IA podem, às vezes, diminuir o desempenho do Agente. Recomenda-se que sejam escritos manualmente e limitados a informações não explícitas que não podem ser inferidas pelo código (cadeias de ferramentas personalizadas, padrões não convencionais, etc.).
Perguntas Frequentes
P1: O Claude Code consegue ler as Skills do diretório .agents/skills/?
Atualmente, o Claude Code, nativamente, descobre e carrega Skills apenas do diretório .claude/skills/. O conteúdo em .agents/skills/ não é reconhecido automaticamente. A comunidade já abriu uma Issue no GitHub (#31005) solicitando que o Claude Code suporte o diretório .agents/. Se suas Skills precisam funcionar no Claude Code, elas devem ser colocadas em .claude/skills/ por enquanto.
P2: A especificação da pasta .agents/ está madura? Posso usá-la em projetos de produção?
A especificação da pasta .agents/ (AGENTS-1 Spec) ainda está em desenvolvimento (Work In Progress). No entanto, o arquivo AGENTS.md já é amplamente adotado – grandes projetos de código aberto como n8n (178K estrelas), llama.cpp (97K estrelas), Bun (82K estrelas), entre outros, já o utilizam. Recomendamos usar AGENTS.md como um arquivo de instruções genérico por enquanto e aguardar a estabilização da especificação completa da estrutura de diretórios .agents/ antes de adotá-la.
P3: Como gerenciar as configurações quando membros da equipe usam ferramentas de IA diferentes (Claude Code + Cursor)?
Recomendamos um gerenciamento em camadas: 1) AGENTS.md para informações gerais do projeto (comandos de build, padrões de codificação), que todas as ferramentas leem; 2) CLAUDE.md para instruções específicas do Claude Code; 3) .cursorrules para regras específicas do Cursor. Coloque as Skills genéricas em .agents/skills/ e as Skills específicas de cada ferramenta em seus respectivos diretórios. Use a APIYI apiyi.com para gerenciar centralmente as invocações de API de IA da equipe, com uma única plataforma cobrindo todos os modelos.
P4: Quais são as diferenças de formato entre SKILL.md e SKILL.yaml?
SKILL.md é o formato do Claude Code, usando um arquivo Markdown com metadados YAML no frontmatter. A parte de instruções é escrita em Markdown, tornando-a mais legível para humanos. SKILL.yaml é o formato da especificação .agents/, definindo tudo em estrutura YAML, o que é mais conveniente para análise por máquinas. As informações centrais (nome, descrição, condições de gatilho) são as mesmas em ambos, apenas o formato difere.
Resumo
A principal diferença entre as pastas .agents e .claude:
- Propósito diferente:
.claude/é o diretório de configuração exclusivo do Claude Code, com integração profunda de todas as suas funcionalidades..agents/é um padrão universal sob a Linux Foundation, compatível com várias ferramentas. - Formato das Skills diferente:
.claude/skills/usaSKILL.md(Markdown), carregado nativamente pelo Claude Code..agents/skills/usaSKILL.yaml(YAML), projetado para ser independente de ferramentas. - Podem coexistir e se complementar: Funcionalidades profundas do Claude Code (Hooks, subagentes, permissões) devem ficar em
.claude/. Habilidades genéricas e portáteis devem ir para.agents/. Instruções básicas do projeto usamAGENTS.md.
A escolha de qual pasta usar depende principalmente da composição da cadeia de ferramentas da sua equipe e das necessidades de portabilidade das habilidades.
Recomendamos o uso da APIYI apiyi.com para gerenciar centralmente as invocações de modelos no desenvolvimento de Agentes de IA. A plataforma oferece cotas gratuitas e uma interface unificada para múltiplos modelos, suportando a integração de modelos populares como Claude, GPT e Gemini.
📚 Referências
-
Documentação Oficial do Claude Code Skills: Definição completa, formato e métodos de uso das Skills.
- Link:
code.claude.com/docs/en/skills - Descrição: Entenda o formato SKILL.md, regras de gatilho e passagem de parâmetros.
- Link:
-
Documentação do Claude Code Sub-agents: Definição e métodos de configuração de Sub-agents.
- Link:
code.claude.com/docs/en/sub-agents - Descrição: Entenda o formato de arquivo do diretório
.claude/agents/.
- Link:
-
Site Oficial do AGENTS.md: Padrão de arquivo de instruções para Agent multi-ferramentas.
- Link:
agents.md - Descrição: Entenda as especificações de escrita do AGENTS.md e a lista de ferramentas suportadas.
- Link:
-
Especificação da pasta
.agents/: Definição completa da estrutura de diretórios do AGENTS-1 Spec.- Link:
github.com/agentsfolder/spec - Descrição: Entenda o design de
manifest.yaml,modes,policies,scopes.
- Link:
-
Central de Documentação APIYI: Gerenciamento unificado de chamadas de API no desenvolvimento de AI Agents.
- Link:
docs.apiyi.com - Descrição: Suporta interface unificada para múltiplos modelos, ideal para cenários de desenvolvimento de Agents.
- Link:
Autor: Equipe de Tecnologia APIYI
Intercâmbio Técnico: Bem-vindo à discussão na seção de comentários, mais informações podem ser encontradas na central de documentação APIYI docs.apiyi.com.
