Distribuir uma Skill em Todos os Agentes

Quando Usar

• Use quando uma skill deve ser disponibilizada em várias pastas de skills de agentes locais.
• Use quando o usuário pede para sincronizar ou distribuir atualizações de skills para outros agentes.

O usuário tem 4 locais de skills de agentes em seu MacBook. Uma skill deve existir em cada um (ou via symlink) para ser descoberta por todos os agentes.

Os 4 Locais Canônicos

Fluxo de Trabalho

1. Crie a skill em ~/.agents/skills/<skill-name>/SKILL.md (canônico). Siga as orientações de effective-agent-skills SKILL.md.
2. Verifique se o symlink .claude está intacto (verificação única):

   ls -la ~/.claude/skills
   # Expect: ~/.claude/skills -> ~/.agents/skills
   

   Se for um diretório real em vez de um symlink, o usuário divergiu cópias — pergunte antes de mexer.
3. Copie apenas para .hermes (.claude e .pi são symlinks — já cobertos):

   SKILL=<skill-name>
   cp -r ~/.agents/skills/$SKILL ~/.hermes/skills/
   

4. Verifique se os 4 locais mostram contagens de bytes idênticas:

   for p in ~/.agents/skills/$SKILL ~/.claude/skills/$SKILL ~/.pi/agent/skills/$SKILL ~/.hermes/skills/$SKILL; do
     echo "$p: $(wc -c < $p/SKILL.md) bytes"
   done
   

   Todos os quatro números devem corresponder. Se .claude ou .pi mostrar uma contagem de bytes diferente, esse symlink está quebrado — investigue antes de prosseguir.

Atualizando uma Skill Distribuída Existente

Mesmo fluxo — recopie de ~/.agents/skills/ para .hermes/skills/. Os symlinks .claude e .pi são atualizados automaticamente. cp -r sobrescreve por padrão; use rsync -a --delete se a pasta de skills tiver arquivos aninhados que podem ter sido removidos:

rsync -a --delete ~/.agents/skills/$SKILL/ ~/.hermes/skills/$SKILL/

Armadilhas

• ~/.pi/skills/ é o local errado. Pi Agent carrega apenas de ~/.pi/agent/skills/. Uma skill colocada em ~/.pi/skills/ é invisível. Se você encontrar skills já lá, elas são órfãs — confirme com o usuário antes de excluir.
• ~/.claude/skills é um symlink, não uma pasta. cp -r ~/.agents/skills/foo ~/.claude/skills/ dará erro com "são idênticos". Pule a cópia explícita do Claude.
• Skills locais de projeto também existem — ./.pi/agent/skills/ (ou .pi/skills/) dentro de um repositório substitui o global em caso de colisão (o último descoberto vence). Esta skill lida apenas com distribuição GLOBAL.
• .pi/agent/skills é um symlink → .agents/skills. Não copie cp para ele (dá erro "são idênticos"); ele sincroniza automaticamente. Apenas .hermes/skills é uma cópia independente — não consolide unilateralmente o Hermes em um symlink a menos que o usuário peça.
• Hermes tira snapshots das skills no início da sessão. Uma skill recém-distribuída não aparecerá dentro de uma sessão Hermes em execução até que seja reiniciada (funciona bem para as outras 3 agentes imediatamente e para sessões futuras).
• A capitalização dos nomes de arquivos importa em volumes sensíveis a maiúsculas/minúsculas. SKILL.md deve ser em maiúsculas.

Quando NÃO Usar Esta Skill

• A skill é específica do projeto → coloque-a em ./.claude/skills/, ./.pi/agent/skills/, etc. dentro do repositório, não globalmente.
• Editar a skill de apenas um agente (por exemplo, um fluxo de trabalho apenas para Hermes) → corrija esse arquivo diretamente, não propague.
• Remover uma skill globalmente é destrutivo. Primeiro, mostre os diretórios exatos da skill que seriam removidos, confirme com o usuário e, em seguida, use o método de exclusão seguro preferido do usuário para ~/.agents/skills/ e ~/.hermes/skills/.

Limitações

• Adaptado de davidondrej/skills; verifique os caminhos locais, ferramentas, credenciais e recursos do agente antes de agir.
• Para comandos, acesso remoto, agendamento, automação de navegador ou fluxos de trabalho de alteração de arquivos, obtenha aprovação explícita do usuário e confirme o ambiente de destino primeiro.