Agent Skills: configuração de .claude/skills e .agents/skills

Em um repositório compartilhado entre Claude Code, Codex, Cursor e Gemini CLI, mantenha os arquivos das skills em .agents/skills/<skill-name>/. Disponibilize cada skill compartilhada para o Claude Code por meio de um link simbólico de diretório com destino relativo em .claude/skills/. Depois, verifique a descoberta e a invocação em cada cliente antes de adotar essa estrutura em toda a equipe.

Essa configuração permite manter uma única cópia editável de cada fluxo de trabalho, respeitando as diferentes regras de descoberta dos clientes. Uma equipe que usa apenas o Claude Code pode continuar com sua estrutura em .claude/skills/; mover os diretórios é útil quando você precisa usar as mesmas skills em outro cliente.

A AAIF padronizou o nome do diretório?

A AAIF hospeda o padrão, enquanto os clientes continuam definindo onde procurar skills. A Anthropic anunciou a doação em 22 de outubro de 2026, e a fundação recebeu Agent Skills como um projeto hospedado.

O guia de implementação para clientes deixa explicitamente o diretório que contém as skills fora dos requisitos da especificação. Ele recomenda considerar .agents/skills/ para interoperabilidade, além do diretório próprio de cada cliente. Essa recomendação não faz com que todos os clientes existentes passem a procurar skills nesse caminho.

A unidade portável é um diretório que contém SKILL.md, um bloco inicial de metadados YAML (frontmatter) e instruções em Markdown. A especificação do formato exige name e description; recursos opcionais podem acompanhá-los. A sintaxe de invocação, os runtimes de scripts e as permissões continuam dependendo do ambiente que executa a skill. Em particular, allowed-tools continua experimental, com suporte variável entre as implementações, portanto não constitui uma política de permissões portável.

Em quais caminhos as quatro ferramentas procuram skills?

Use os diretórios de descoberta documentados para o sistema de arquivos local, listados abaixo. Os caminhos e controles deste guia refletem a documentação oficial em 2026-10-26; acrescente <skill-name>/SKILL.md a cada diretório para obter a estrutura usada aqui.

Ferramenta	Diretórios no repositório	Diretórios do usuário	Escolha para um repositório compartilhado
Claude Code	`.claude/skills/`	`~/.claude/skills/`	Adicione um alias por skill de `.claude/skills/` para o diretório compartilhado.
Codex CLI e extensão para IDE	`.agents/skills/`	`~/.agents/skills/`	Leia diretamente o diretório compartilhado.
Cursor Agent	`.agents/skills/`, `.cursor/skills/`; também `.claude/skills/` e `.codex/skills/` para compatibilidade	Os mesmos quatro nomes de diretório dentro de `~/`	Use `.agents/skills/`; nenhum alias adicional para o Cursor é necessário.
Gemini CLI	`.agents/skills/` e `.gemini/skills/`	`~/.agents/skills/` e `~/.gemini/skills/`	Leia `.agents/skills/` diretamente. Ele tem precedência sobre `.gemini/skills/` dentro do mesmo escopo.

O guia atual do Claude Code não lista a descoberta nativa de .agents/skills/, e a solicitação de recurso #31005 continua aberta. Por sua vez, os guias do Codex e do Gemini acima não listam .claude/skills/ como diretório de descoberta. Use os caminhos documentados, sem tratar esses diretórios como universalmente intercambiáveis.

Esses são caminhos de descoberta local. Uma skill no diretório pessoal do seu notebook não fica automaticamente disponível em um worker remoto ou em um contêiner recém-criado; esse ambiente também precisa receber os arquivos.

Crie uma skill compartilhada e um alias para o Claude Code

Armazene a skill completa em .agents/skills/ e crie um link para seu diretório, incluindo eventuais scripts ou referências adicionados no futuro. Um alias por skill também deixa espaço para as skills específicas do Claude que já existem.

Tenha o Git e um cliente instalado e autenticado que já consiga trabalhar no seu repositório. Nenhuma nova credencial de API é necessária para essa configuração do sistema de arquivos; o acesso normal ao cliente e as permissões das ferramentas continuam valendo.

Escreva a skill portável

Crie .agents/skills/review-staged/SKILL.md no seu editor, criando os diretórios que o contêm se necessário. Se essa skill já existir, escolha outro nome e ajuste o diretório, o frontmatter e os comandos de maneira consistente.

Cole este arquivo completo:

---
name: review-staged
description: "Review staged Git changes for correctness before a commit. Use when the user asks to review the Git index or staged changes."
---

Begin the answer with `Skill loaded: review-staged`.

1. Locate the repository root with `git rev-parse --show-toplevel`.
   Run all following commands from that directory.
2. Run `git diff --cached --name-only`. If it prints no paths,
   report `No staged changes.` and stop.
3. Run `git diff --cached --check` and `git diff --cached --`.
   Treat a nonzero `--check` exit as evidence to report, not a reason
   to skip reading the diff.
4. Read relevant files as needed. Report concrete correctness issues
   with file and line references. Separate confirmed issues from questions.
5. Finish with suggested verification commands. Do not claim they ran.

Do not edit files, stage changes, or create a commit.

O fluxo de trabalho revisa o índice do Git: as alterações preparadas para o próximo commit. A referência de diff do Git documenta --cached para essa comparação e --check para erros de espaços em branco e marcadores de conflito. O exemplo pede ao agente que execute comandos comuns, sem depender de mecanismos de expansão de prompts específicos de cada cliente.

Adicione o alias no Bash do macOS ou Linux

Crie um link simbólico relativo para essa skill. O Claude Code documenta explicitamente o suporte a diretórios de skills com links simbólicos.

Execute o seguinte em Bash, de qualquer local dentro do repositório Git desejado:

(
  set -eu
  cd "$(git rev-parse --show-toplevel)"
  test -f .agents/skills/review-staged/SKILL.md
  mkdir -p .claude/skills

  skill_link=.claude/skills/review-staged
  if [ -e "$skill_link" ] || [ -L "$skill_link" ]; then
    printf '%s\n' "Already exists: $skill_link" >&2
    exit 1
  fi

  ln -s ../../.agents/skills/review-staged "$skill_link"
  test -L "$skill_link"
  test -f "$skill_link/SKILL.md"
  readlink "$skill_link"
)

A saída esperada é ../../.agents/skills/review-staged, com código de saída 0. Os dois componentes .. são relativos ao diretório que contém o link, .claude/skills/, e retornam à raiz do repositório.

Se o destino já existir, inspecione-o antes de alterar qualquer coisa. Mantenha um alias existente que esteja correto; se houver um diretório real de skill, compare-o com a cópia canônica e decida como conciliá-los. O comando se recusa a substituir tanto um diretório quanto um link com destino inexistente.

Crie o link equivalente no Windows

Use PowerShell 7.1 ou posterior para criar o link relativo de diretório abaixo. A documentação de New-Item da Microsoft documenta esse requisito de versão; a criação de links simbólicos no Windows normalmente exige privilégios elevados ou uma versão compatível do Windows com o Modo de Desenvolvedor habilitado.

Com o SKILL.md canônico já salvo, execute o seguinte a partir da raiz do repositório:

New-Item -ItemType Directory -Force -Path '.claude/skills' -ErrorAction Stop | Out-Null
Push-Location '.claude/skills' -ErrorAction Stop
try {
    New-Item -ItemType SymbolicLink -Path 'review-staged' `
        -Target '../../.agents/skills/review-staged' -ErrorAction Stop | Out-Null
    Get-Item 'review-staged' | Select-Object LinkType, Target
    Test-Path 'review-staged/SKILL.md' -PathType Leaf
}
finally {
    Pop-Location
}

O valor de LinkType deve ser SymbolicLink, e a verificação do arquivo deve retornar True. Se a criação falhar por falta de privilégios, use o procedimento de habilitação do Modo de Desenvolvedor ou de execução com privilégios elevados aprovado pela sua organização.

Não presuma que o Git Bash nativo se comporte como no Linux: o Git for Windows documenta que o comportamento padrão de ln -s cria cópias. Use o procedimento em PowerShell e inspecione o link resultante.

Outro tipo de falha pode aparecer após clonar o repositório. Com core.symlinks=false, o Git faz o checkout de um link simbólico como um arquivo comum que contém o texto do destino. Faça o diagnóstico em PowerShell:

git config --show-origin --get core.symlinks
Get-Item '.claude/skills/review-staged' |
    Select-Object LinkType, Target, PSIsContainer
Test-Path '.claude/skills/review-staged/SKILL.md' -PathType Leaf

Se o alias for um arquivo de texto, inspecione seu conteúdo antes de substituir esse arquivo específico por um link real. Configure o suporte a links simbólicos no checkout para os próximos clones. Alterar a configuração do Git por si só não converte um arquivo de texto que já passou pelo checkout em um link de diretório.

Verifique a descoberta, a ativação e a saída

Verifique primeiro o catálogo do cliente e depois invoque a skill explicitamente. A existência de um arquivo no disco não prova que o cliente o descobriu, e uma entrada no catálogo não prova que suas instruções foram carregadas.

Abra ou inicie cada cliente na raiz do repositório. Use estes controles dentro do cliente, não em um prompt do Bash ou do PowerShell:

Cliente	Confirmar a descoberta	Invocar o exemplo
Claude Code	Execute `/skills`; use `/reload-skills` se necessário, conforme documentado na referência de comandos.	Envie `/review-staged`.
Codex CLI ou extensão para IDE	Abra `/skills` ou o seletor de skills `$`.	Envie `$review-staged Review my staged changes.`
Cursor Agent	Abra Customize → Skills e encontre a skill no seletor `/`.	Selecione `review-staged` e peça uma revisão das alterações preparadas para commit.
Gemini CLI	Execute `/skills list`; use `/skills reload` depois de adicionar arquivos.	Peça: `Use the review-staged skill to review my staged changes.`

O fluxo de ativação documentado do Gemini usa activate_skill e uma solicitação interativa de consentimento. Aprove o diretório da skill desejada quando solicitado. O guia de gerenciamento cobre os comandos de listagem e recarregamento.

A resposta esperada começa com Skill loaded: review-staged, seguida das observações e verificações sugeridas, ou de No staged changes. quando o índice está vazio. Além dessa mensagem, inspecione o registro de ativação ou de leitura do arquivo e os comandos do Git. Isso confirma que o fluxo de trabalho foi carregado; não confirma que todas as observações da revisão estão corretas.

O Cursor lê os dois caminhos dessa estrutura. Suas notas de versão do IDE 3.25, de 14 de outubro de 2026, informam que skills com o mesmo nome podem aparecer como linhas separadas no menu. Verifique se há entradas duplicadas na versão instalada; não presuma que todos os clientes eliminem aliases duplicados da mesma maneira.

Use uma estrutura previsível para monorepos e CI

Mantenha as skills compartilhadas na raiz do repositório e inicie cada cliente nesse local até validar a primeira configuração. Para fluxos específicos de um pacote, mencione o pacote na descrição e nas instruções da skill, em vez de depender de uma descoberta idêntica de diretórios aninhados. O exemplo acima revisa deliberadamente todo o índice do Git.

Uma estrutura prática atribui uma responsabilidade a cada local:

Local	Responsabilidade
`.agents/skills/review-staged/SKILL.md`	Instruções compartilhadas que serão mantidas.
`.agents/skills/review-staged/references/`	Documentos de apoio opcionais distribuídos com essa skill.
`.claude/skills/review-staged`	Alias relativo para o diretório completo da skill compartilhada.
`packages/mobile/`	Código da aplicação mencionada na tarefa solicitada.

As regras de escopo variam. Claude Code e Codex percorrem os diretórios acima do ponto de partida até a raiz do repositório em busca de seus respectivos diretórios de skills. O Cursor também documenta skills de projeto aninhadas cujo escopo abrange os arquivos abaixo do diretório que as contém. O guia de gerenciamento do Gemini descreve as skills do workspace em relação ao diretório atual. Iniciar os quatro clientes na raiz evita depender dessas diferenças.

Mantenha cada skill compartilhada em um subdiretório imediatamente abaixo do diretório de skills. O guia de primeiros passos do Gemini limita a descoberta a essa profundidade; a descoberta recursiva do Cursor não torna portável uma camada adicional de categorias.

Para um workspace que contenha apenas um pacote, repita a verificação de descoberta nesse workspace e instale ou vincule a skill compartilhada ali, se necessário. Não reutilize o destino ../../ do alias da raiz em um local mais profundo sem recalculá-lo.

Inclua o diretório canônico e o link simbólico relativo no commit se os ambientes de checkout da equipe oferecerem suporte a essa estrutura. Mantenha o destino dentro do repositório para que um clone novo possa resolvê-lo sem acessar o diretório pessoal de um desenvolvedor.

Em um checkout de CI no Linux, esta verificação em Bash confere os arquivos e o link necessários:

test -f .agents/skills/review-staged/SKILL.md &&
test -L .claude/skills/review-staged &&
test -f .claude/skills/review-staged/SKILL.md

O código de saída 0 indica que essas verificações do sistema de arquivos passaram. A descoberta e a invocação pelo cliente ainda precisam ser verificadas, conforme descrito acima, no ambiente de execução real.

Se a skill ainda não carregar, verifique a camada que falhou

Corrija a camada que falhou em vez de alterar o prompt repetidamente. Estas são alternativas de diagnóstico, não uma sequência de configurações que todos devem mudar.

Ausente do catálogo: Confirme a raiz do workspace, a grafia do diretório e o nome exato do arquivo SKILL.md. Leia o arquivo pelo caminho que o cliente verifica. Se o caminho canônico funcionar, mas o caminho do Claude falhar, corrija o link ou o checkout.
Arquivo encontrado, metadados rejeitados: Verifique os delimitadores YAML, uma description não vazia com no máximo 1024 caracteres e a correspondência entre o nome do diretório e o campo name, com 1–64 caracteres entre letras minúsculas, dígitos e hifens. Evite hifens no início, no fim ou consecutivos.
Arquivo novo ainda não aparece: Recarregue as skills do Claude ou do Gemini com os comandos acima. O Codex documenta a detecção automática, com a reinicialização como alternativa; reabra o Cursor quando for necessário repetir a descoberta realizada na inicialização.
Skill do workspace ausente no Gemini: Verifique a confiança da pasta por meio de /permissions trust. A referência de configuração atual lista skills.enabled como true por padrão, mas uma política de administrador pode proibir skills. Resolva uma configuração desabilitada ou uma decisão de confiança pelos controles apropriados.
A skill errada é executada: Inspecione as cópias pessoais e de projeto que tenham o mesmo nome. O Claude dá prioridade às skills pessoais sobre as do projeto; o Codex pode listar ambas; o Gemini dá prioridade às skills do workspace sobre as do usuário. Prefira nomes distintos para fluxos de trabalho realmente diferentes.
Listada, mas não selecionada automaticamente: Invoque-a explicitamente primeiro. Se funcionar, melhore a descrição para identificar a tarefa que ela atende. Uma descrição mais clara ajuda na seleção; mover um arquivo que já é descoberto corretamente não ajuda.
Carregada, mas os comandos falham: Verifique a disponibilidade do Git, o diretório de trabalho e o erro de permissão informado. A portabilidade dos diretórios não instala um runtime nem concede permissão para executar comandos.