BreetyGreen/Myco

compartilhamento-de-skills-multi-agente

Instale uma skill uma vez e faça com que todos os agentes de IA de codificação trabalhando no mesmo repositório possam lê-la e invocá-la à sua própria maneira.

Esta skill é independente de ferramenta. Funcione quer você use dois agentes ou seis.

Quando usar

• Você usa múltiplos produtos de codificação de IA no mesmo projeto (por exemplo, Claude Code
  • Codex + Cursor) e deseja que uma skill / conjunto de regras / prompt seja compartilhado e alternável entre eles.
• Alguém pergunta "por que apenas uma ferramenta pode usar esta skill?" ou "por que não posso chamá-la na ferramenta X?"
• Uma skill está instalada, mas um agente não consegue encontrá-la.
• Você quer que uma skill viva dentro do repositório e viaje com o Git, para que sobreviva a uma nova máquina ou a um novo colega de equipe.

O modelo mental central (leia isto primeiro, ou você instalará errado)

Não existe um diretório compartilhado de skills entre agentes. "Instale uma vez, todas as ferramentas veem" é literalmente falso. Cada produto lê skills de um diretório diferente, e a sintaxe de invocação também difere.

O compartilhamento real é alcançado instalando a skill em diretórios por agente que vivem dentro do repositório, para que viajem com o Git. Uma cópia física por agente, todas com commit, todas sincronizadas.

Onde cada agente lê skills + como invocá-las

⚠️ Verifique os caminhos com a versão atual de cada ferramenta antes de confiar nesta tabela. Essas convenções mudam rapidamente. Última verificação: 2026-07 (veja "Verificação" abaixo). Em caso de dúvida, consulte a própria documentação da ferramenta ou explore o sistema de arquivos.

Agente	Diretório no nível do repositório (viaja com Git)	Diretório no nível do usuário	Como invocar
Claude Code	<repo>/.claude/skills/	~/.claude/skills/	Mencione a skill pelo nome no chat. Alguns conjuntos (por exemplo, gstack) adicionam comandos /slash por cima.
WorkBuddy	<repo>/.workbuddy/skills/	~/.workbuddy/skills/	Mencione a skill pelo nome (mesma convenção do Claude Code).
Codex CLI	<repo>/.agents/skills/ e/ou <repo>/.codex/skills/ (veja nota)	~/.agents/skills/ ou ~/.codex/skills/ (veja nota)	$nome-da-skill, o seletor /skills, ou apenas nomeie-a no prompt. NÃO é um comando /slash estilo /design.
Cursor	<repo>/.cursor/skills/ (também lê .cursor/rules/ .mdc)	—	Regras são injetadas automaticamente; também tolera skills em .agents/.
Antigravity	<repo>/.antigravity/skills/ (baseado em VS Code, convenção)	—	Mencione a skill pelo nome; caminho do fornecedor não verificado.
Gemini CLI	<repo>/.agents/skills/	—	Descoberta automática; nomeie-a no prompt.
Cline	<repo>/.cline/skills/, .clinerules/skills/, ou .claude/skills/	~/.cline/skills/	Nomeie-a; ativada por um toggle experimental.

Duas coisas que as pessoas erram sobre o Codex

1. .agents/skills/ vs .codex/skills/. A documentação oficial da OpenAI lista os níveis de descoberta como sistema → admin (/etc/codex/skills) → usuário ($HOME/.agents/skills) → repositório (.agents/skills). Na prática, muitas instalações leem ~/.codex/skills/ e <repo>/.codex/skills/ em vez disso, e ~/.agents/ pode nem existir na máquina. Isso é desvio de versão. A jogada segura: instale em AMBOS .agents/skills/ e .codex/skills/ no nível do repositório (são cópias Markdown baratas), ou defina a variável de ambiente CODEX_SKILLS_PATH para um diretório que você controla.

2. Skills do Codex NÃO são acionadas por comandos /slash. Use $nome-da-skill, o seletor /skills, ou mencione o nome. Um comando como /design é uma extensão gstack específica do Claude Code — outros produtos não o têm. (O antigo mecanismo de prompt personalizado ~/.codex/prompts/ do Codex está obsoleto; não construa sobre ele.)

💡 Convenção emergente: .agents/ está se tornando o caminho padrão entre agentes no repositório — Codex, Gemini CLI e Cursor o aceitam, e o Cline tolera .claude/skills/. Quando você puder manter apenas um caminho, .agents/skills/ é a melhor aposta única para portabilidade futura.

Passos

1. Identifique a fonte e a forma da skill

• É uma skill SKILL.md padrão (tem name: no frontmatter)?
• Markdown puro, ou inclui scripts executáveis?

# Liste qualquer coisa que NÃO seja documentação — scripts potenciais para auditar
find <skill-src> -type f ! -name '*.md' ! -name '*.txt'

Se incluir scripts, audite-os antes de distribuir.

2. Avalie o tamanho — decida se pode viver no repositório

du -sh <skill-dir>

• Leve (alguns KB–MB, Markdown puro) → faça commit no repositório. Esta é a única maneira de obter compartilhamento verdadeiro entre múltiplos agentes.
• Pesado (inclui node_modules, centenas de MB–GB) → instalação global apenas. Não pode ir no repositório (incharia o projeto e poluiria as transferências). Tal skill é utilizável apenas pelo produto para o qual foi criada; documente essa limitação explicitamente.

3. Detecte quais agentes estão em uso

# Diretórios do usuário
ls -d ~/.claude ~/.codex ~/.agents ~/.cursor ~/.cline 2>/dev/null
# Diretórios do repositório
ls -d .claude .codex .agents .cursor .cline 2>/dev/null

Ou apenas pergunte ao usuário quais ferramentas ele usa.

4. Distribua em cada diretório do agente no nível do repositório

Se você já tem uma boa cópia, o caminho mais rápido é distribuí-la. Cada skill deve estar exatamente um nível de profundidade em seu próprio subdiretório (os agentes não fazem recursão).

macOS / Linux:

cd <repo>
mkdir -p .claude/skills .agents/skills .codex/skills
# Distribua de uma cópia boa conhecida (preserva subdiretórios por skill):
cp -R .claude/skills/. .agents/skills/
cp -R .claude/skills/. .codex/skills/

Windows (PowerShell):

cd <repo>
New-Item -ItemType Directory -Force .\.claude\skills, .\.agents\skills, .\.codex\skills | Out-Null
Copy-Item -Recurse -Force .\.claude\skills\* .\.agents\skills\
Copy-Item -Recurse -Force .\.claude\skills\* .\.codex\skills\

Ao distribuir de um repositório fonte com muitas skills, use o name do frontmatter de cada skill como nome do seu subdiretório. O engine/distribute.py incluso automatiza isso em várias plataformas.

5. Verifique a colocação

for d in .claude/skills .agents/skills .codex/skills; do
  echo "=== $d ==="; ls "$d" 2>/dev/null | wc -l
done
head -5 .agents/skills/<uma-skill>/SKILL.md   # verifique o frontmatter

Confirme se todos os diretórios de destino existem, as contagens coincidem e o frontmatter central SKILL.md está intacto.

6. Escreva notas de roteamento em AGENTS.md

AGENTS.md na raiz do repositório é lido diretamente pelo Codex (e frequentemente linkado simbolicamente para CLAUDE.md). Adicione uma seção curta declarando quais skills vivem onde, quem pode usá-las e a sintaxe de invocação correta por ferramenta — especialmente a nota de que o Codex não usa /slash. Se o projeto tiver um sistema de documentação, adicione um docs/SKILLS_GUIDE.md mais completo e indexe-o a partir de AGENTS.md.

7. Faça commit — não está "compartilhado" até estar no Git

Os novos diretórios .claude/skills, .agents/skills, .codex/skills não estão rastreados. O compartilhamento só acontece quando eles estão com commit; caso contrário, uma nova máquina perde tudo.

git add .claude/skills .agents/skills .codex/skills AGENTS.md
git commit -m "chore: compartilhar skills entre agentes de IA"

Armadilhas

• Tratar uma instalação no nível do usuário (~/...) como "compartilhamento". Ela não viaja com o Git e morre em uma nova máquina. O compartilhamento deve ir dentro do repositório.
• Assumir que existe um diretório comum. Não existe. Cada produto lê seu próprio caminho.
• Assumir que o Codex usa /slash para executar skills. Ele usa $nome-da-skill / /skills / uma menção ao nome. /xxx é um mecanismo de prompt personalizado obsoleto.
• Apostar em um único caminho do Codex. .agents/skills/ e .codex/skills/ ambos aparecem na prática — instale ambos, ou defina CODEX_SKILLS_PATH.
• Fazer commit de uma skill de tamanho GB (com node_modules) no repositório. Isso incha o projeto e polui as transferências. Skills pesadas permanecem apenas globais.
• Esquecer de fazer commit. Instalar sem commit = sem compartilhamento.

Verificação

• O diretório de skills no nível do repositório de cada agente de destino existe, as contagens de skills coincidem e o frontmatter central SKILL.md é válido.
• AGENTS.md (e opcionalmente docs/SKILLS_GUIDE.md) registra a sintaxe de invocação por ferramenta, explicitamente anotando que o Codex não usa /slash.
• As alterações estão com commit no Git.

---

Última verificação: 2026-07 contra as convenções do Claude Code, WorkBuddy, Codex CLI, Cursor, Antigravity (além de Gemini CLI e Cline). Os caminhos de descoberta de skills mudam frequentemente — verifique novamente a documentação de cada ferramenta se algo não resolver.