AGENTS.md e Agent Skills: o que eu aprendi abrindo o capô dos AI Coding Agents

Neste material eu explico, do jeito que eu gostaria que tivessem me explicado, o que é o AGENTS.md, o que são Agent Skills, como tudo isso funciona por debaixo dos panos, e no final entrego um tutorial passo a passo para você implementar cada parte no seu repositório hoje.

Parte 1: Explicação

1.1 O README que a IA lê

Pensa comigo: o README.md existe para humanos. Ele explica o que o projeto faz, como instalar, como contribuir. Mas um agente de IA precisa de informações completamente diferentes:

• Qual o comando de build?
• Qual o style guide?
• Como rodar um teste individual?
• Quais padrões arquiteturais seguir?

A resposta que a comunidade encontrou foi criar um "README para máquinas". É exatamente isso que o AGENTS.md é: um arquivo Markdown que fica na raiz do seu repositório (ou em subdiretórios, no caso de monorepos) contendo instruções direcionadas a agentes de IA.

1.2 Por que um padrão aberto importa

Antes do AGENTS.md, cada ferramenta inventava o seu próprio arquivo proprietário.

Antes do AGENTS.md

Cada ferramenta adotava sua própria forma de armazenar contexto para agentes de IA.

Claude Code

• Arquivo: CLAUDE.md

Cursor

• Arquivo: .cursor/rules/

Windsurf

• Estrutura baseada em Memories e Rules

GitHub Copilot

• Arquivo: .github/copilot-instructions.md

O resultado era fragmentação. A mesma informação precisava ser mantida em múltiplos formatos dependendo da ferramenta utilizada.

Isso criava fragmentação. Se você trabalhava com duas ferramentas, mantinha dois arquivos dizendo a mesma coisa. O AGENTS.md nasceu como um padrão aberto e agnóstico de ecossistema, e hoje é suportado por mais de 20 ferramentas, incluindo Codex (OpenAI), Cursor, Antigravity (Google DeepMind), Jules (Google), GitHub Copilot Coding Agent, Windsurf, OpenCode, Aider, Zed, Warp, RooCode, Gemini CLI e Devin. Segundo o site oficial agents.md, mais de 60.000 repositórios públicos no GitHub já incluem um context file.

Na minha visão de quem já viu muita guerra de padrões, isso é o tipo de convergência que vale a pena abraçar cedo.

1.3 O que vai dentro de um AGENTS.md

O conteúdo típico cobre quatro blocos:

# AGENTS.md

## Build & Test
- Build: `npm run build`
- Test all: `npm test`
- Test single: `npm test -- --grep "test name"`
- Lint: `npm run lint`

## Code Style
- Use TypeScript strict mode
- Prefer `const` over `let`
- Avoid `try/catch` where possible
- Single-word variable names preferred

## Architecture
- API handlers in `src/api/handlers/`
- Database models in `src/models/`
- Avoid circular dependencies

## Testing
- Avoid mocks when possible
- Test actual implementation

O princípio central que eu defendo aqui é: seja conciso e prático. Nada de textos longos explicando a filosofia do projeto. O agente precisa de regras claras e comandos executáveis. Guarde essa frase, porque a pesquisa científica que vou citar no final confirma exatamente isso.

1.4 Hierarquia: do global ao local

Uma feature poderosa do padrão é a hierarquia de arquivos. No OpenCode, por exemplo, existem três níveis:

~/.config/opencode/AGENTS.md      → Global (todas as sessões)
./AGENTS.md                       → Projeto (raiz do repo)
./packages/frontend/AGENTS.md     → Pacote específico (monorepo)

A regra é simples: o arquivo mais próximo tem prioridade. Isso permite que um monorepo tenha regras globais na raiz (formatting, naming, convenções gerais) e regras específicas em cada pacote (framework React 19, CSS com Tailwind v4, testes com Vitest, por exemplo).

1.5 Como funciona sob o capô: o caso OpenCode

Aqui é onde a coisa fica interessante de verdade. O artigo abre o código-fonte do OpenCode (que é open source e tem uma implementação limpa) e mostra três mecanismos.

Mecanismo 1: Descoberta

O primeiro passo é descobrir quais arquivos de instrução existem. No OpenCode, isso acontece no arquivo instruction.ts, que define uma lista de arquivos em ordem de prioridade:

// Arquivos que o sistema procura, em ordem de prioridade
const FILES = [
  "AGENTS.md",
  "CLAUDE.md",
  "CONTEXT.md", // deprecated
]

A busca acontece em duas frentes simultâneas:

Frente 1: configuração global do usuário. O sistema verifica se o desenvolvedor tem um AGENTS.md "pessoal", que vale para todos os projetos. Fica em diretórios de configuração do sistema operacional (como ~/.config/opencode/). Pense nisso como as suas preferências universais: estilo de código que você gosta, ferramentas que sempre usa.

function globalFiles() {
  const files = []
  files.push(path.join(Global.Path.config, "AGENTS.md"))
  // Compatibilidade: também busca CLAUDE.md do Claude Code
  if (!Flag.OPENCODE_DISABLE_CLAUDE_CODE_PROMPT) {
    files.push(path.join(os.homedir(), ".claude", "CLAUDE.md"))
  }
  return files
}

Frente 2: contexto do projeto. Em paralelo, o sistema percorre a árvore de diretórios de baixo para cima (do diretório de trabalho atual até a raiz do repositório), coletando todos os AGENTS.md que encontrar pelo caminho:

// Busca hierárquica: sobe do diretório atual até a raiz do worktree
const matches = await Filesystem.findUp(file, Instance.directory, Instance.worktree)

Regra de prioridade em caso de conflito: o arquivo mais próximo (mais específico) vence. E AGENTS.md tem prioridade sobre CLAUDE.md, que tem prioridade sobre CONTEXT.md.

Mecanismo 2: Injeção no system prompt

Uma vez descobertos, os arquivos são lidos e injetados diretamente no system prompt do LLM. No loop principal do agente (prompt.ts):

// Montagem do system prompt
const system = [
  ...await SystemPrompt.environment(model),  // Info do ambiente (OS, diretório, data)
  ...await InstructionPrompt.system()        // ← AGENTS.md entra aqui
]

O conteúdo do AGENTS.md é prefixado com "Instructions from: /caminho/do/AGENTS.md" e concatenado ao prompt de sistema. Isso significa que toda mensagem que o LLM processa já contém as instruções do seu repositório. A montagem final do system prompt segue esta ordem:

1. Prompt base do modelo (Anthropic, GPT, Gemini)
2. Informações do ambiente (OS, diretório, data, git status)
3. Conteúdo do AGENTS.md (build, test, style guide)
4. Definição das tools (read, write, bash, grep, skill)

Mecanismo 3: Lazy loading de instruções aninhadas

Aqui está um detalhe elegante que eu não conhecia antes de ler o código. O OpenCode implementa um carregamento contextual sob demanda: quando o agente lê um arquivo em um subdiretório (por exemplo, src/components/Button.tsx), o sistema verifica se existe um AGENTS.md naquele subdiretório e, se existir, injeta seu conteúdo automaticamente:

export async function resolve(messages, filepath, messageID) {
  let current = path.dirname(filepath)
  const root = path.resolve(Instance.directory)

  // Sobe do diretório do arquivo até a raiz
  while (current.startsWith(root) && current !== root) {
    const found = await find(current)
    // Injeta se: existe, não é o arquivo raiz, e não foi carregado antes
    if (found && !system.has(found) && !already.has(found)) {
      const content = await Filesystem.readText(found)
      results.push({ filepath: found, content })
    }
    current = path.dirname(current)
  }
}

O agente só recebe as instruções de um subdiretório quando realmente está trabalhando nele. Sem poluir o contexto desnecessariamente.

1.6 Agent Skills: blocos modulares de comportamento

Se o AGENTS.md é o "manual do projeto", as Agent Skills são um conceito mais sofisticado: blocos modulares de comportamento que o agente pode carregar sob demanda.

Uma skill é um diretório contendo um arquivo SKILL.md com instruções especializadas. O formato segue YAML frontmatter mais corpo em Markdown:

---
name: git-release
description: Create consistent releases and changelogs
---

## What I do
- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me
Use this when you are preparing a tagged release.

Skills podem conter arquivos adicionais como scripts, templates e referências:

my-skill/
├── SKILL.md          # Instruções principais (obrigatório)
├── reference.md      # Docs detalhados (carregados sob demanda)
├── examples/
│   └── sample.md     # Exemplos (carregados sob demanda)
└── scripts/
    └── helper.py     # Script utilitário (executado, não carregado)

1.7 Progressive Disclosure: o padrão que faz tudo escalar

Esse é o conceito mais importante do material inteiro, na minha opinião. Progressive disclosure é um padrão de design de UI emprestado para a arquitetura de agentes de IA. A ideia:

"

Em vez de carregar tudo no contexto do LLM de uma vez (o que consome tokens, aumenta custo e pode confundir o modelo), revele informações gradualmente, conforme a necessidade.

O mecanismo funciona em três camadas:

As três camadas do Progressive Disclosure

Layer 1 - Indexação

O que carrega

• Nome da skill
• Descrição da skill

Quando

• Sempre presente no prompt

Custo

• Aproximadamente 50 tokens

Layer 2 - Ativação

O que carrega

• Conteúdo completo do SKILL.md

Quando

• Quando o modelo chama a tool skill()

Custo

• Aproximadamente 500 tokens

Layer 3 — Referência

O que carrega

• Scripts
• Exemplos
• Documentação auxiliar

Quando

• Sob demanda via leitura de arquivos

Custo

• Aproximadamente 2000 tokens ou mais

Por que isso importa? A janela de contexto de um LLM é um recurso finito e precioso. Cada token desperdiçado com informação irrelevante é um token a menos para raciocínio. Progressive disclosure resolve isso: o modelo sabe o que existe (Layer 1), carrega como usar quando decidir (Layer 2), e acessa detalhes profundos se precisar (Layer 3).

1.8 Como o OpenCode implementa Skills

Descoberta (skill.ts)

O algoritmo de descoberta é multi-diretório e multi-escopo:

// Diretórios externos compatíveis
const EXTERNAL_DIRS = [".claude", ".agents"]
const EXTERNAL_SKILL_PATTERN = "skills/**/SKILL.md"
const OPENCODE_SKILL_PATTERN = "{skill,skills}/**/SKILL.md"

A ordem de busca garante que projeto sobrescreve global:

1. Global: ~/.claude/skills/*/SKILL.md
2. Global: ~/.agents/skills/*/SKILL.md
3. Projeto: .claude/skills/*/SKILL.md (sobe hierarquicamente)
4. Projeto: .agents/skills/*/SKILL.md (sobe hierarquicamente)
5. Config: .opencode/skills/*/SKILL.md
6. Custom: caminhos configurados em opencode.json
7. Remote: skills baixadas via URL (index.json)

A compatibilidade cross-tool é intencional: uma skill criada para Claude Code em .claude/skills/ funciona automaticamente no OpenCode.

A tool skill como mecanismo de disclosure (tool/skill.ts)

A mágica acontece na definição da tool skill. O OpenCode injeta o índice de todas as skills disponíveis diretamente na descrição da ferramenta:

const description = [
  "Load a specialized skill that provides domain-specific instructions.",
  "",
  "Available skills:",
  "",
  "<available_skills>",
  ...accessibleSkills.flatMap((skill) => [
    `  <skill>`,
    `    <name>${skill.name}</name>`,
    `    <description>${skill.description}</description>`,
    `  </skill>`,
  ]),
  "</available_skills>",
].join("\n")

Isso é a Layer 1: o modelo vê na descrição da tool quais skills existem e o que fazem. Ele ainda não carregou nenhuma, isso consumiu apenas alguns tokens para os metadados.

Quando o modelo decide que precisa de uma skill, ele chama a tool:

skill({ name: "git-release" })

E a tool retorna o conteúdo completo (Layer 2) junto com uma lista dos arquivos disponíveis no diretório da skill (Layer 3):

return {
  title: `Loaded skill: ${skill.name}`,
  output: [
    `<skill_content name="${skill.name}">`,
    `# Skill: ${skill.name}`,
    skill.content.trim(),        // ← Layer 2: corpo do SKILL.md
    `Base directory: ${base}`,
    `<skill_files>`,
    files,                       // ← Layer 3: arquivos disponíveis
    `</skill_files>`,
    `</skill_content>`,
  ].join("\n"),
}

Os arquivos da Layer 3 (scripts, exemplos, referências) são listados mas não carregados. O modelo pode então usar a tool de leitura de arquivos para acessá-los se necessário.

Skills remotas (discovery.ts)

O OpenCode vai além e suporta registries de skills remotas. Você pode configurar uma URL que aponta para um index.json:

{
  "skills": [
    {
      "name": "cloudflare",
      "description": "Cloudflare platform skill",
      "files": ["SKILL.md", "references/workers.md", "references/d1.md"]
    }
  ]
}

O sistema faz download, cache local, e as skills ficam disponíveis como qualquer outra. Isso abre a porta para skill marketplaces e compartilhamento entre times.

1.9 O fluxo completo, da inicialização à execução

Consolidando tudo em um fluxo narrativo. Quando você inicia uma sessão com um AI coding agent:

1. Inicialização: o sistema descobre AGENTS.md (global e projeto) e descobre skills (escopos, config, agents/URLs)

2. Montagem: monta o system prompt (base do modelo, info do ambiente, conteúdo do AGENTS.md, definição das tools com o índice de skills embutido)

3. Interação e execução: a cada mensagem sua, o LLM processa tudo como system prompt; quando precisa, chama skill() e o conteúdo é injetado; quando lê arquivos em subdiretórios, o lazy loading injeta AGENTS.md locais

O ponto central: o modelo opera em dois níveis de contexto simultâneos. O AGENTS.md fornece o "como trabalhamos aqui" (sempre presente), enquanto as Skills fornecem o "como fazer isso especificamente" (sob demanda).

1.10 Panorama: como cada ferramenta implementa

Claude Code

• Arquivo de contexto: CLAUDE.md
• Skills: suporte completo
• Progressive Disclosure: 3 camadas
• Hierarquia de arquivos: findUp
• Geração automática: /init
• Skills remotas: plugins
• Compatibilidade AGENTS.md: fallback

OpenCode

• Arquivo de contexto: AGENTS.md
• Compatibilidade adicional: CLAUDE.md
• Skills: suporte completo
• Progressive Disclosure: 3 camadas
• Hierarquia de arquivos: findUp
• Geração automática: /init
• Skills remotas: URLs (index.json)

Cursor

• Arquivo de contexto: .cursor/rules/
• Skills: parcial (via regras)
• Progressive Disclosure: direto no prompt
• Hierarquia de arquivos: File Matchers
• Geração automática: via LLM
• Compatibilidade AGENTS.md: sim

Codex

• Arquivo de contexto: AGENTS.md
• Skills: via MCP
• Progressive Disclosure: parcial
• Hierarquia de arquivos: sim
• Geração automática: /init
• Compatibilidade AGENTS.md: nativa

Windsurf

• Arquivo de contexto: Memories + Rules
• Skills: Workflows
• Progressive Disclosure: direto no prompt
• Hierarquia de arquivos: sim
• Geração automática: via LLM
• Compatibilidade AGENTS.md: sim

"

Destaque: o OpenCode implementa compatibilidade bidirecional. Ele lê tanto AGENTS.md quanto CLAUDE.md e também busca skills em .claude/skills/, .agents/skills/ e .opencode/skills/.

1.11 O que a ciência diz: o caso contra-intuitivo

Em fevereiro de 2026, pesquisadores da ETH Zurich publicaram o paper "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" (Gloaguen, Mündler et al.), o primeiro estudo rigoroso sobre a efetividade real dos context files.

Eles criaram o AGENT BENCH, um benchmark com 138 instâncias de tarefas reais (bug fixes e features), 12 repositórios recentes e de nicho com context files escritos por devs reais, cobertura média de testes de 75%, avaliando 4 modelos (Sonnet 4.5, GPT-5.2, GPT-5.1 Mini e Qwen3-30B).

Os achados desafiam a intuição.

Resultado do estudo

Sem context file

• Taxa de sucesso: baseline
• Custo computacional: baseline

Context file gerado por LLM

• Taxa de sucesso: aproximadamente 3% pior
• Consumo de recursos: aproximadamente 20% maior

Context file escrito por humano

• Taxa de sucesso: aproximadamente 4% melhor
• Consumo de recursos: aproximadamente 20% maior

Sim, você leu certo: context files gerados automaticamente pelo agente (via /init) tendem a piorar o desempenho, enquanto os escritos por humanos oferecem apenas uma melhoria marginal de aproximadamente 4%.

A análise de traces revelou quatro causas:

1. Mais exploração: com context files, os agentes executam mais grep, leem mais arquivos e rodam mais testes

2. Mais raciocínio: o número de tokens de raciocínio sobe de 14% a 22% (o modelo "pensa mais" para seguir as instruções)

3. Instruções seguidas: os agentes realmente seguem as instruções (por exemplo, usam uv quando mencionado), mas isso nem sempre ajuda

4. Redundância: context files gerados por LLM são altamente redundantes com a documentação existente

O insight mais valioso: quando os pesquisadores removeram toda a documentação (README, docs/, exemplos) e deixaram apenas o context file, os arquivos gerados por LLM passaram a ajudar (+2,7%). Isso sugere que context files são mais úteis em repositórios com pouca ou nenhuma documentação.

A recomendação dos autores: omitir context files gerados por LLM por enquanto, contrariamente às recomendações dos desenvolvedores de agentes, e incluir apenas requisitos mínimos (tooling específico para usar com o repositório).

Traduzindo para a minha linguagem de produção: menos é mais. Um AGENTS.md com 10 linhas de build commands é mais útil que um de 200 linhas gerado automaticamente.

Parte 2: Tutorial passo a passo

Agora vamos colocar a mão na massa. Eu organizei o tutorial na mesma ordem em que você vai precisar das coisas em um projeto real.

Passo 1: Crie o AGENTS.md na raiz do projeto

Na raiz do seu repositório, crie o arquivo:

touch AGENTS.md

Preencha seguindo o princípio de concisão. Use este template como ponto de partida e adapte para a sua stack:

# AGENTS.md

## Build & Test
- Build: `npm run build`
- Test all: `npm test`
- Test single: `npm test -- --grep "nome do teste"`
- Lint: `npm run lint`

## Code Style
- TypeScript strict mode
- Prefira `const` em vez de `let`
- Nomes de variáveis descritivos e curtos

## Architecture
- Handlers de API em `src/api/handlers/`
- Models de banco em `src/models/`
- Evite dependências circulares

## Testing
- Evite mocks quando possível
- Teste a implementação real

Regras de ouro que eu sigo, validadas pela pesquisa da ETH Zurich:

1. Escreva você mesmo. Não delegue para o /init e aceite o resultado cegamente

2. Comece pelos comandos executáveis (build, test, lint). Esse é o conteúdo de maior valor por token

3. Não repita o que já está no README. Redundância foi uma das causas de piora identificadas no estudo

4. Mire em 10 a 30 linhas, não em 200

Passo 2: Configure o AGENTS.md global (preferências pessoais)

Crie o arquivo de preferências universais, que vale para todos os seus projetos:

mkdir -p ~/.config/opencode
touch ~/.config/opencode/AGENTS.md

Coloque aqui apenas o que é seu, não do projeto:

# Preferências globais

- Responda em português brasileiro
- Prefira soluções simples a abstrações prematuras
- Sempre rode o lint antes de finalizar

Se você usa Claude Code, o equivalente é ~/.claude/CLAUDE.md. O OpenCode lê os dois por compatibilidade.

Passo 3: Adicione AGENTS.md por pacote (monorepos)

Se o seu projeto é um monorepo, crie arquivos específicos em cada pacote:

touch packages/frontend/AGENTS.md
touch packages/api/AGENTS.md

Exemplo para o frontend:

# Frontend

- Framework: React 19
- CSS: Tailwind v4
- Test: Vitest
- Componentes em `src/components/`, um diretório por componente

Lembre da regra de prioridade: o arquivo mais próximo sobrescreve o mais distante. A raiz carrega as regras gerais, o pacote carrega as específicas. E graças ao lazy loading, o agente só recebe as instruções do pacote quando estiver trabalhando em arquivos dele.

Passo 4: Crie a sua primeira Agent Skill

Escolha um workflow repetitivo do seu time. Release é um ótimo primeiro candidato. Crie a estrutura:

mkdir -p .claude/skills/git-release
touch .claude/skills/git-release/SKILL.md

Eu recomendo o diretório .claude/skills/ justamente pela compatibilidade cross-tool: funciona no Claude Code e no OpenCode sem mudar nada.

Preencha o SKILL.md com frontmatter YAML e corpo Markdown:

---
name: git-release
description: Create consistent releases and changelogs
---

## What I do
- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me
Use this when you are preparing a tagged release.

Dois campos do frontmatter merecem atenção especial:

• name: identificador único, em kebab-case
• description: essa linha é o que o modelo vê na Layer 1, antes de carregar qualquer coisa. Escreva pensando em "como o modelo vai decidir usar essa skill". Seja específico sobre o quando, não apenas o quê

Passo 5: Adicione arquivos de apoio à skill (Layer 3)

Quando a skill crescer, mova detalhes para arquivos auxiliares em vez de inchar o SKILL.md:

cd .claude/skills/git-release
touch reference.md
mkdir -p examples scripts
touch examples/sample.md
touch scripts/helper.py

A estrutura final:

git-release/
├── SKILL.md          # Instruções principais (obrigatório, Layer 2)
├── reference.md      # Docs detalhados (Layer 3, carregado sob demanda)
├── examples/
│   └── sample.md     # Exemplos (Layer 3)
└── scripts/
    └── helper.py     # Script utilitário (executado, não carregado no contexto)

A regra mental que eu uso para decidir onde cada coisa vai:

• Vai no SKILL.md: o que o modelo precisa para executar o caso comum
• Vai em reference.md ou examples/: o que ele só precisa em casos específicos
• Vai em scripts/: lógica determinística que é melhor executar do que pedir para o modelo reproduzir

Passo 6: Teste o progressive disclosure na prática

Abra uma sessão do agente no seu projeto e valide as três camadas:

1. Layer 1: pergunte ao agente "quais skills você tem disponíveis?". Ele deve listar a git-release pelo nome e descrição, sem ter carregado o conteúdo

2. Layer 2: peça "prepare uma release". O agente deve chamar a tool skill, e você verá o conteúdo do SKILL.md sendo injetado

3. Layer 3: se a tarefa exigir, o agente vai listar e ler reference.md ou os exemplos via tool de leitura de arquivos

Se o agente nunca ativa a skill quando deveria, o problema quase sempre está na description do frontmatter. Reescreva deixando claro o gatilho de uso.

Passo 7: Configure escopo global para skills pessoais

Skills que você usa em todos os projetos vão para o diretório home:

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

A ordem de resolução garante que, se existir uma skill com o mesmo nome no projeto e no global, a do projeto vence. Use isso a seu favor: defaults pessoais no global, sobrescritas específicas no repo.

Passo 8 (opcional): Skills remotas para o time

Se você quer compartilhar skills entre times sem copiar diretórios, publique um index.json em uma URL acessível:

{
  "skills": [
    {
      "name": "cloudflare",
      "description": "Cloudflare platform skill",
      "files": ["SKILL.md", "references/workers.md", "references/d1.md"]
    }
  ]
}

E configure a URL no opencode.json do projeto. O sistema baixa, faz cache local e disponibiliza as skills como se fossem locais. É o embrião de um skill marketplace interno.

Passo 9: Audite e enxugue

Por fim, o passo que quase ninguém faz e que a pesquisa mostrou ser o mais importante. Depois de algumas semanas de uso:

1. Releia o seu AGENTS.md e corte tudo que é redundante com o README ou com a documentação existente

2. Verifique nos logs ou traces se o agente está seguindo instruções que não agregam (mais exploração e mais tokens de raciocínio sem ganho de resultado)

3. Se você gerou o arquivo via /init, reescreva manualmente. O estudo mostrou que arquivos gerados por LLM pioram o desempenho em média

4. Mantenha apenas requisitos mínimos: tooling específico, comandos de build e teste, convenções que não estão documentadas em nenhum outro lugar

Resumo executivo

Se eu tivesse que condensar tudo isso em cinco frases para um colega Staff, seria assim:

1. AGENTS.md é o README para máquinas: comandos executáveis e regras claras, injetados no system prompt do agente

2. A hierarquia (global, raiz, subdiretório) com lazy loading permite contexto preciso sem poluir a janela do modelo

3. Agent Skills são blocos modulares de comportamento, e o segredo da escalabilidade delas é o progressive disclosure em três camadas: índice sempre presente, conteúdo sob ativação, referências sob demanda

4. A compatibilidade cross-tool já é realidade: uma skill em .claude/skills/ funciona no Claude Code e no OpenCode

5. A ciência confirma o instinto de engenharia: escreva você mesmo, seja mínimo, evite redundância. Um AGENTS.md de 10 linhas vale mais que um de 200 gerado automaticamente