Partilhe skills entre repos sem cópias divergentes

Como partilhar competências de agentes entre repositórios

Para partilhar competências de agentes entre repositórios, deixe de copiar o ficheiro e passe a depender dele. Mantenha um repositório de competências, crie tags e permita que cada projeto fixe uma tag. Depois, adicione um teste de verificação por competência e reveja cada atualização da mesma forma que revê a atualização de uma dependência.

Isto envolve quatro partes: uma fonte de verdade partilhada, uma versão fixada por repositório, um teste de verificação por competência e um processo de revisão. O conteúdo abaixo explica por que motivo cada parte existe, como as ferramentas lançadas em 2026 lidam com esta questão e como criar toda a estrutura num remote git autoalojado, sem depender de serviços externos.

Uma competência de agente é uma pasta que contém um ficheiro SKILL.md, além dos scripts e ficheiros de referência necessários. Se esta unidade for nova para si, leia primeiro o que é uma competência de agente e como funciona o SKILL.md. Esta página aborda a cadeia de fornecimento dessa unidade.

Onde uma skill fica e por que é difícil partilhá-la

O Claude Code carrega skills de três locais, e a documentação das skills indica cada caminho.

• ~/.claude/skills/<skill-name>/SKILL.md é pessoal. É carregada em todos os seus projetos e em nenhum projeto de outras pessoas.
• .claude/skills/<skill-name>/SKILL.md é ao nível do projeto. É carregada por qualquer pessoa que faça checkout desse repositório.
• <plugin>/skills/<skill-name>/SKILL.md vem incluída num plugin. É carregada onde quer que esse plugin esteja ativado.

A segunda opção é a mais útil para uma equipa, porque fica no repositório e é obtida por todas as pessoas que o clonam. Também é aí que começam os problemas. Uma skill em .claude/skills/ pertence a um repositório. Tem oito repositórios. Portanto, a skill é copiada oito vezes.

O frontmatter não ajuda. A especificação Agent Skills permite seis chaves, e as ferramentas de distribuição que aplicam essa regra mostram a lista quando se usa outra:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Repare no que falta: não existe uma chave version. Nada dentro do ficheiro regista qual das cópias é mais recente. Isto é razoável, porque uma skill é um documento e não um pacote. Mas significa que o versionamento tem de ser fornecido pela camada envolvente do ficheiro, e essa camada fica a seu cargo.

Problema um: oito cópias que divergem silenciosamente

Copiar e colar funciona no primeiro dia. Falha ao fim de sessenta dias. Alguém corrige uma instrução errada no repositório payments e não altera os outros sete. Outra pessoa adiciona uma regra sobre paginação em orders. Agora, o mesmo nome de skill produz duas revisões diferentes, dependendo do diretório a partir do qual o agente foi iniciado, e nenhum dos developers sabe disso.

A falha é silenciosa porque não existe um estado de erro. Uma skill é prosa. Uma instrução desatualizada produz uma resposta confiante e errada, que é o tipo mais dispendioso. Nada no agente compara a sua cópia com a de outras pessoas. O único sinal é alguém perceber que dois repositórios não coincidem.

Problema dois: nada fixa uma versão

Mesmo quando uma equipa mantém as competências num único local, o método habitual de partilha é um passo de cópia: um script de configuração, uma linha curl na documentação de integração ou um alias de shell que sincroniza uma pasta. Todos esses métodos instalam o conteúdo que está atualmente no topo do branch.

Isto significa que dois programadores no mesmo commit da mesma aplicação podem estar a executar instruções diferentes, porque fizeram a sincronização em dias diferentes. Também significa que não é possível responder à pergunta importante depois de uma execução problemática do agente: qual foi a versão da competência que produziu este resultado? Sem uma revisão registada, a execução não é reproduzível e o relatório do erro não permite uma investigação concreta.

Problema três: ninguém sabe se a skill continua a funcionar

Uma skill não tem compilador. É um conjunto de instruções dirigido a um modelo, por isso pode deixar de funcionar mesmo que o ficheiro permaneça idêntico, byte a byte. Uma atualização do modelo altera o grau de rigor com que uma instrução longa é seguida. Uma ferramenta de linha de comandos chamada pela skill muda o nome de uma flag. Um URL num ficheiro de referência começa a devolver 404 e o agente passa a trabalhar a partir da página de erro.

Nenhum destes casos gera uma falha explícita. O agente continua a responder. A resposta apenas fica pior do que estava no mês passado, o que é difícil de detetar um pull request de cada vez.

O que as ferramentas lançadas em 2026 resolvem

Já estão a surgir várias respostas, mas não há consenso sobre onde a versão deve ficar.

Ficheiros de bloqueio. A ferramenta de linha de comandos skills da Vercel Labs (vercel-labs/skills, licenciada sob MIT, v1.5.22 em 5 de agosto de 2026) instala skills de um repositório git no diretório esperado pelo seu agente e conhece a estrutura de mais de setenta agentes. npx skills add <repo> instala, npx skills update atualiza e npx skills list mostra o que está instalado. O registo do que está instalado é mantido uma vez por utilizador, e não uma vez por repositório. Existe um pedido aberto nesse projeto (issue 283) para um comando skills install que reinstale todas as skills registadas a partir do ficheiro de bloqueio, de modo que uma segunda máquina termine com o mesmo conjunto. Considere esse pedido um indicador do estado atual. A ideia do ficheiro de bloqueio está consolidada. A parte por projeto ainda está a ser desenvolvida.

Especificações e testes. O SkillSpec segue a abordagem oposta. Trata um SKILL.md como um contrato a verificar, e não como prosa em que se deve confiar, com o objetivo declarado de tornar as skills "fáceis de seguir, testáveis e comprováveis". skillspec doctor <path> indica onde é provável que um agente perca o contexto. skillspec boundary map <path> indica a que recursos a skill pode aceder, e skillspec boundary assess <path> classifica essas descobertas por risco. É um crate Rust, com licenciamento duplo MIT ou Apache 2.0, na versão 0.2.2 em 29 de julho de 2026. Instale a versão fixada, e não a mais recente:

cargo install skillspec --version 0.2.2 --locked
skillspec --version

--locked compila com as versões das dependências com que o crate foi publicado, para que a compilação não mude inesperadamente. skillspec --version deve imprimir 0.2.2. Um número diferente significa que um binário mais antigo, presente anteriormente no seu PATH, está a ser usado.

Práticas dos fornecedores. A Google descreveu como cria as skills em google/skills, numa publicação sobre como cria, testa e dimensiona skills de agentes. Retirando a escala da equação, o mecanismo é uma integração contínua (CI) normal. Antes de serem integradas, todas as skills passam por linters que verificam os metadados do frontmatter, o número de linhas, a estrutura dos diretórios e a nomenclatura. Um verificador de ligações faz a compilação falhar quando qualquer URL devolve 404, detetando assim a ligação plausível que um agente inventou. Os autores têm de fornecer, juntamente com a skill, um conjunto de prompts de avaliação e uma grelha de pontuação. Os trabalhos de avaliação agendados são executados semanalmente contra toda a biblioteca para detetar regressões. Cada skill tem também um responsável identificado, que deve corrigi-la quando a qualidade diminui.

O padrão por trás das três respostas

Não precisa de escolher uma dessas opções. Por baixo delas existe uma única estrutura, e o git simples fornece tudo o que é necessário.

1. Uma única fonte de verdade. A skill tem exatamente uma localização, e cada repositório referencia essa localização em vez de manter uma cópia.
2. Uma versão fixada por repositório. Cada projeto regista a revisão exata que utiliza. Assim, uma atualização é um commit nesse projeto, com autor e data.
3. Um teste de smoke por skill. Uma verificação executável que comprova que a skill continua a produzir o resultado prometido.
4. Um processo de revisão. Uma alteração numa skill partilhada passa por revisão, e cada consumidor vê um diff antes de a adotar.

Essa é a estrutura de uma dependência. As skills tornaram-se artefactos partilhados mais rapidamente do que as ferramentas à sua volta evoluíram. Por isso, as ferramentas em que já confia são a opção mais segura.

Um layout para uma equipa pequena num repositório Git self-hosted

Um repositório contém as competências. Não há mais nada nele, por isso o histórico funciona como um changelog das instruções.

agent-skills/
  skills/
    api-review/
      SKILL.md
    release-notes/
      SKILL.md
  tests/
    api-review.sh
    release-notes.sh
  CHANGELOG.md

As releases são tags. Use tags anotadas, porque incluem uma mensagem e uma data. Escreva a mensagem como o motivo pelo qual um consumidor quereria fazer a atualização:

git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0

Se o seu remoto for Gitea, Forgejo, GitLab ou um repositório bare através de SSH no seu próprio VPS, nada do que se segue muda. Tudo aqui é git mais um symlink.

Fixar uma versão com um submódulo git

Um submódulo regista um commit exato de outro repositório dentro do seu repositório. Esse registo é a versão fixada. Em cada projeto consumidor:

git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"

O link simbólico é a parte que faz isto funcionar. Uma entrada de skill ao nível do projeto pode ser um link simbólico para um diretório noutro local do disco, e o Claude Code segue-o e lê SKILL.md no destino. Assim, a skill é carregada como uma skill normal do projeto, enquanto os ficheiros ficam no submódulo, no commit escolhido.

Verifique a versão fixada:

git submodule status

Uma linha correta começa por um espaço, seguida do commit, do caminho e da tag mais próxima:

 4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)

Um - inicial significa que o submódulo nunca foi inicializado, pelo que .claude/skills/api-review não aponta para nada e a skill não é carregada, sem produzir qualquer indicação. Corrija isto com git submodule update --init. Um + inicial significa que o commit obtido é diferente do commit registado, pelo que esse developer está a executar instruções que mais ninguém tem. Os novos clones precisam de git clone --recurse-submodules, e essa linha deve ficar no README, porque um clone simples deixa vendor/agent-skills vazio e não apresenta nenhum erro.

A atualização é deliberada, que é precisamente o objetivo:

git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"

A linha diff é o caminho para a revisão. Mostra a mesma alteração que todos os outros repositórios consumidores verão e pode ser incluída num pull request.

Fixação com um marketplace de plugins

Se preferir não pedir a todos os developers que aprendam a utilizar submodules, o sistema de plugins do Claude Code trata da distribuição por si e funciona com um repositório remoto self-hosted. Coloque um catálogo em .claude-plugin/marketplace.json no repositório de skills:

{
  "name": "acme-agents",
  "owner": { "name": "Platform team", "email": "platform@example.com" },
  "plugins": [
    {
      "name": "team-skills",
      "description": "Shared review and release skills",
      "version": "1.4.0",
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0",
        "sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
      }
    }
  ]
}

Existem aqui duas fontes diferentes, e confundi-las é o erro mais comum. A fonte do marketplace, ou seja, o local de onde o próprio catálogo é obtido, aceita ref para uma branch ou tag e não aceita sha. Uma fonte de plugin dentro do catálogo aceita ambos e, quando os dois estão definidos, sha é a fixação efetiva. Por isso, a fixação para um commit exato pertence à entrada do catálogo.

Cada repositório consumidor declara então o marketplace no seu .claude/settings.json versionado:

{
  "extraKnownMarketplaces": {
    "acme-agents": {
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0"
      }
    }
  },
  "enabledPlugins": {
    "team-skills@acme-agents": true
  }
}

Um colega que confie na pasta do projeto recebe um pedido para instalar o marketplace, e o plugin fica ativado sem ser necessário indicar essa ação numa página wiki. As skills passam a responder a /team-skills:api-review, porque as skills dos plugins usam o namespace do nome do plugin e não entram em conflito com uma skill do projeto com o mesmo nome. Depois de publicar uma nova tag, os consumidores atualizam com /plugin marketplace update acme-agents e executam /reload-plugins se o resumo da instalação o solicitar.

Escrever um smoke test para uma skill

Um smoke test é uma execução automatizada de um agente contra um fixture com uma falha conhecida, acompanhada de uma única asserção. O Claude Code é executado de forma não interativa com -p, e uma skill invocada pelo utilizador também funciona nesse modo: inclua /skill-name na string do prompt para que seja expandido antes do início da execução.

#!/usr/bin/env bash
set -euo pipefail

claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --allowedTools "Read" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
  | jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/null

fixtures/orders-api.md é um ficheiro curto com uma falha deliberada. A asserção verifica se a skill a identifica. jq -e termina com um código diferente de zero quando o seu filtro produz null, por isso uma skill que deixe de detetar a falha introduzida faz o script falhar. O próprio claude termina com um código diferente de zero quando a execução falha, e set -euo pipefail transforma qualquer uma das falhas num teste falhado.

Um modelo reformula as respostas entre execuções, por isso nunca faça a asserção sobre uma frase completa. Faça a asserção sobre um identificador que a skill deva emitir ou sobre um campo de um esquema solicitado, e mantenha o fixture pequeno para que a execução continue económica.

Na CI, adicione --bare. Sem essa opção, claude -p carrega o mesmo contexto que uma sessão interativa carregaria, incluindo hooks, plugins e CLAUDE.md da máquina onde é executado. Assim, a configuração pessoal de um colega pode alterar o resultado. O modo bare ignora toda a descoberta automática, o que também faz com que ignore a skill que está a testar. Por isso, carregue essa skill explicitamente. O modo bare também não lê o login da sua subscrição, por isso defina ANTHROPIC_API_KEY no ambiente primeiro:

claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --plugin-dir vendor/agent-skills \
  --allowedTools "Read" \
  --output-format json

Com --output-format stream-json, o primeiro evento da execução indica quais plugins foram carregados e inclui um array plugin_errors com os que não foram carregados. Faça o job da CI falhar quando plugin_errors não estiver vazio. Isto deteta uma pinagem dirigida a uma revisão que já não existe, um problema que, de outro modo, aparece como o agente a ignorar silenciosamente as regras internas.

Uma skill compartilhada é uma instrução executável

Duas funcionalidades tornam isso literal, e ambas são importantes quando o ficheiro vem de outra equipa.

Primeiro, uma SKILL.md pode executar comandos shell antes de o modelo ler qualquer conteúdo. Uma linha como esta no corpo é pré-processamento:

- Current branch: !`git rev-parse --abbrev-ref HEAD`

O comando é executado na máquina que carrega a skill, e o resultado substitui o marcador de posição no texto que o modelo recebe. Um bloco delimitado iniciado com três crases seguidas de ! executa vários comandos da mesma forma. Ninguém aprova isto durante a execução. Ler uma skill compartilhada significa ler as substituições de comandos que ela contém.

Segundo, o frontmatter pode pré-aprovar ferramentas. allowed-tools concede as ferramentas listadas sem um pedido de permissão durante o turno que invocou a skill. Numa skill de projeto, essa concessão passa a aplicar-se depois de alguém aceitar a caixa de diálogo de confiança do workspace para a pasta. A documentação do Claude Code declara a consequência de forma clara: reveja as skills de projeto antes de confiar num repositório, porque uma skill pode conceder a si própria acesso amplo a ferramentas.

Por isso, trate uma atualização de skill exatamente como uma atualização de dependência. Fixe-a pelo commit exato sempre que o mecanismo permitir, porque uma tag pode ser movida e uma branch move-se por definição. Numa máquina com acesso restrito, "disableSkillShellExecution": true nas definições substitui cada substituição de comando pelo texto literal [shell command execution disabled by policy] em vez de a executar, e, quando aplicado através de definições geridas, o utilizador não pode alterá-lo. As skills incluídas e geridas estão isentas dessa definição.

A mesma atenção aplica-se ao que uma skill lê. Uma skill que executa env ou abre um ficheiro de configuração introduz no contexto do modelo tudo o que encontrar. Esta é a falha abordada em manter segredos fora dos agentes que executa. Uma skill que obtém uma página ou executa uma consulta expõe esse mesmo conteúdo para o exterior, porque o texto obtido entra no contexto com exatamente o mesmo aspeto das instruções que escreveu. Este é um limite que vale a pena compreender antes de apontar um agente para a sua própria instância SearXNG para pesquisa na Web.

O que ler ao atualizar uma versão

• O diff de cada corpo SKILL.md, porque esse texto é a instrução que o seu agente vai seguir.
• Cada substituição de comandos, porque elas são executadas na sua máquina quando a skill é carregada.
• Qualquer alteração em allowed-tools, porque essa linha concede acesso a ferramentas sem pedir confirmação.
• A execução dos testes associada à tag. Se o repositório partilhado executar os seus próprios smoke tests na CI, a tag que está a fixar deve ter uma execução bem-sucedida associada.

Um revisor que não consiga ler todo o diff em dez minutos está a analisar uma skill que cresceu demasiado. Divida-a. O mesmo princípio aplica-se aos documentos do repositório que os seus agentes leem: mantenha as regras duradouras nos ficheiros descritos em na separação entre AGENTS.md e HUMAN.md e o raciocínio arquitetural num DESIGN.md escrito para agentes, e mantenha as skills como procedimentos específicos.

Quando uma alteração no modelo ou na ferramenta quebra uma skill

Várias coisas podem mudar por baixo de uma skill sem que alguém a edite. Uma atualização do modelo altera a consistência com que uma instrução longa é seguida. Assim, uma skill que dependia de o modelo chegar ao passo nove pode deixar de chegar lá. Uma ferramenta de linha de comandos muda o nome de uma flag. O agente executa a flag antiga, lê o erro e improvisa. Um URL referenciado começa a devolver 404. O harness do agente altera a forma como seleciona as skills. Assim, um description que antes ganhava a correspondência pode deixar de ganhar. Quando um procedimento começa a terminar mais cedo dessa forma, nenhum aumento de versão o corrige. As próprias instruções precisam de uma estrutura que force a execução dos últimos passos. Esta é a abordagem por trás de a skill unlazy e o seu método Depth Tree.

É por isso que o smoke test tem um papel central nesta configuração. Execute o teste de cada skill segundo um agendamento e também a cada push. A Google executa semanalmente os seus jobs de avaliação contra toda a biblioteca por este motivo. Para uma equipa com dez skills, um job cron semanal num VPS pequeno é suficiente. É a única forma de detetar a falha antes de um developer.

A portabilidade também ajuda. A especificação Agent Skills limita o frontmatter a seis chaves. Assim, uma skill escrita de acordo com essa especificação é carregada por ferramentas além daquela para a qual foi criada. Cada chave específica do harness que adicionar é uma aposta num único fornecedor. Escrever skills que resistam à mudança de modelo é uma disciplina própria, abordada em fazer uma skill funcionar em qualquer modelo.

FAQ

Como partilho uma skill de agente entre vários repositórios?

Coloque a skill num repositório git dedicado, crie tags para as versões e faça com que cada projeto consumidor faça referência a uma tag, em vez de copiar o ficheiro. Existem dois mecanismos. Um submódulo git regista um commit exato, e um symlink de .claude/skills/<name> para o submódulo faz com que a skill seja carregada como uma skill normal do projeto. Um plugin marketplace faz o mesmo através de /plugin, com o pin declarado no .claude/settings.json do repositório consumidor. Ambos registam a versão no histórico do git, permitindo identificar quais instruções produziram uma determinada execução do agente.

Posso fixar uma skill de agente numa versão específica?

Não a partir de SKILL.md, porque esse frontmatter não tem uma chave version. O pin tem de vir da camada envolvente do ficheiro. Um submódulo git fixa um commit exato por definição. Num plugin marketplace do Claude Code, uma fonte de plugin aceita ref para um branch ou uma tag e sha para um commit exato; sha tem precedência quando ambos estão presentes. A fonte do marketplace aceita apenas ref. Prefira o pin para um commit, porque uma tag pode ser alterada depois de a rever.

O que deve verificar um teste básico de uma skill?

Verifique algo estável. Execute a skill de forma não interativa contra um fixture que contenha uma falha conhecida e confirme depois que um identificador específico aparece na saída, como o ID de uma regra que a skill deve reportar. Solicitar uma saída estruturada com --output-format json e --json-schema torna a verificação exata, e jq -e faz o script falhar quando o valor está ausente. Nunca verifique uma frase completa, porque um modelo reformula as respostas entre execuções.

É seguro instalar uma skill partilhada a partir do repositório de outra equipa?

Trate-a como uma dependência de código, porque é uma instrução executável. Uma SKILL.md pode executar comandos shell no momento do carregamento através da forma de substituição de comandos !, e o campo de frontmatter allowed-tools pode pré-aprovar ferramentas sem apresentar uma confirmação. Leia o diff em cada atualização, fixe a dependência num commit exato em vez de num branch e prefira uma fonte controlada pela sua própria equipa. Em máquinas geridas, "disableSkillShellExecution": true nas definições impede completamente a execução de substituições de comandos.

Uma skill partilhada funciona noutros agentes além do Claude Code?

Depende do frontmatter utilizado. A especificação Agent Skills define seis chaves: name, description, license, compatibility, metadata e allowed-tools. Uma skill limitada a essas chaves é carregada nas ferramentas que implementam a especificação e também é carregada no Claude Code sem alterações. Chaves específicas do harness e funcionalidades do corpo que não fazem parte da especificação são ignoradas ou rejeitadas noutros locais. Por isso, mantenha-as fora de qualquer skill que pretenda partilhar amplamente.