Como compartilhar skills entre repos sem drift

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 central de competências, crie uma tag 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 isto e como criar toda a estrutura num remote git autoalojado, sem utilizar 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 em torno 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 de 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 obtenha esse repositório.
• <plugin>/skills/<skill-name>/SKILL.md é distribuída dentro de um plugin. É carregada onde quer que esse plugin esteja ativado.

A segunda opção é a mais útil para uma equipa, porque é versionada no repositório e todas as pessoas que o clonarem a recebem. 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 os caminhos de distribuição que a aplicam mostram a lista quando utiliza outra:

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

Repare no que está ausente: 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, não um pacote. Mas significa que o versionamento tem de vir da camada em redor 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 revisões diferentes, dependendo do diretório a partir do qual o agente foi iniciado, e nenhum dos programadores 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 caro. Nada no agente compara a sua cópia com a de outra pessoa. 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 é uma etapa 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 que estiver atualmente no topo do branch.

Isto significa que dois developers no mesmo commit da mesma aplicação podem estar a executar instruções diferentes, porque executaram 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: que versão da competência produziu este resultado? Sem uma revisão registada, a execução não é reproduzível e o relatório de erro não permite uma investigação eficaz.

Problema três: ninguém sabe se a skill ainda funciona

Uma skill não tem compilador. É um conjunto de instruções dirigido a um modelo, por isso pode deixar de funcionar embora o ficheiro permaneça idêntico, byte a byte. Uma atualização do modelo altera o grau de cumprimento de uma instrução longa. 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 trabalha a partir da página de erro.

Nenhum destes casos gera uma falha evidente. O agente continua a responder. A resposta apenas fica pior do que estava no mês passado, o que é difícil de detetar quando se analisa 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.

Lockfiles. A ferramenta de linha de comandos skills da Vercel Labs (vercel-labs/skills, licenciada sob MIT, na versão v1.5.22 em 5 de agosto de 2026) instala skills de um repositório git no diretório esperado pelo seu agent e conhece a estrutura de mais de 70 agents. 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. Um pedido aberto nesse projeto (issue 283) solicita um comando skills install que reinstale todas as skills registadas a partir do lock file, para que uma segunda máquina fique com o mesmo conjunto. Considere esse pedido um indicador do estado atual. A ideia do lockfile está consolidada. A componente 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 validar, e não como texto em que se deve confiar, com o objetivo declarado de tornar as skills "fáceis de seguir, testáveis e demonstráveis". skillspec doctor <path> indica onde é provável que um agent perca o contexto. skillspec boundary map <path> indica o que a skill consegue alcançar, e skillspec boundary assess <path> ordena essas descobertas por risco. É um crate Rust, licenciado duplamente sob MIT ou Apache 2.0, na versão 0.2.2 em 29 de julho de 2026. Instale a versão fixada em vez da 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 apresentar 0.2.2. Um número diferente significa que um binário mais antigo, localizado anteriormente no seu PATH, está a ser usado.

Prática dos fornecedores. A Google descreveu como cria as skills em google/skills, num artigo sobre como cria, testa e dimensiona agent skills. Retirando a escala da equação, o mecanismo é uma integração contínua (CI) normal. Cada skill passa por linters que validam os metadados de frontmatter, o número de linhas, a estrutura dos diretórios e a nomenclatura antes de ser integrada. Um verificador de links falha a compilação quando qualquer URL devolve 404, detetando links plausíveis inventados por um agent. Os autores têm de fornecer, juntamente com a skill, um conjunto de prompts de avaliação e uma grelha de pontuação. As tarefas de avaliação agendadas são executadas semanalmente em toda a biblioteca para detetar regressões, e cada skill tem um responsável identificado que deve corrigir os problemas quando a qualidade diminui.

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

Você não precisa escolher nenhuma delas. Por baixo delas existe uma única estrutura, e o git puro fornece tudo o que é necessário.

1. Uma única fonte de verdade. A skill tem exatamente um local de referência, e cada repositório aponta para esse local em vez de manter uma cópia.
2. Uma versão fixada por repositório. Cada projeto regista a revisão exata que utiliza, portanto atualizar consiste em fazer um commit nesse projeto, com autor e data.
3. Um teste de funcionamento por skill. Uma verificação executável 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 aceitar.

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

Um layout para uma equipa pequena num repositório git remoto autoalojado

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 versões são tags. Use tags anotadas, porque incluem uma mensagem e uma data. Escreva a mensagem como o motivo pelo qual um consumidor quereria atualizar:

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 por SSH no seu próprio VPS, nada do que se segue muda. Tudo aqui é git e um symlink.

Fixaçã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 fixação. 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 é o que torna isto possível. 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 a partir do destino. Assim, a skill é carregada como uma skill normal do projeto, enquanto os ficheiros permanecem no submódulo, no commit que escolheu.

Verifique a fixação:

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 - no início significa que o submódulo nunca foi inicializado, portanto .claude/skills/api-review não aponta para nada e a skill não é carregada silenciosamente. Corrija isso com git submodule update --init. Um + no início significa que o commit verificado é diferente do commit registado, portanto esse desenvolvedor está a executar instruções que mais ninguém tem. Os novos clones precisam de git clone --recurse-submodules, e essa linha deve estar 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. Ela mostra a mesma alteração que todos os outros repositórios consumidores verão e pode ser incluída num pull request.

Em alternativa, fixe a versão através de um marketplace de plugins

Se preferir não pedir a todos os programadores que aprendam a usar submódulos, o sistema de plugins do Claude Code trata da distribuição por si e funciona com um remote autoalojado. 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"
      }
    }
  ]
}

Aqui estão envolvidas duas fontes diferentes, e confundi-las é o erro mais comum. A origem do marketplace, ou seja, o local de onde o próprio catálogo é obtido, aceita ref para uma branch ou tag, mas não aceita sha. Uma origem de plugin dentro do catálogo aceita ambos e, quando ambos estão definidos, sha é a referência efetivamente fixada. Por isso, a fixação num commit exato deve ficar na 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ária uma página wiki a explicar como o fazer. As skills ficam disponíveis através de /team-skills:api-review, porque as skills dos plugins usam o nome do plugin como namespace e não podem colidir 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 agendada do agente contra um fixture com uma falha conhecida, acompanhada de uma asserção. O Claude Code é executado de forma não interativa com -p, e uma skill invocada pelo utilizador funciona nesse modo: coloque /skill-name na cadeia de texto 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 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 asserções sobre uma frase completa. Faça a asserção sobre um identificador que a skill deve emitir ou sobre um campo de um esquema que tenha solicitado. 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. Isso significa que também ignora a skill que está a testar, pelo que deve carregá-la explicitamente. O modo bare também não lê o login da sua subscrição. Por isso, defina primeiro ANTHROPIC_API_KEY no ambiente:

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 os plugins 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. Isso deteta uma referência fixada a uma revisão que já não existe. Caso contrário, o agente pode simplesmente ignorar as regras da sua organização sem indicar o motivo.

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

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

Primeiro, uma SKILL.md pode executar comandos de 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 a respetiva saída substitui o marcador de posição no texto que o modelo recebe. Um bloco delimitado iniciado com três acentos graves seguidos de ! executa vários comandos da mesma forma. Ninguém aprova nada disto durante a execução. Ler uma skill partilhada significa ler as substituições dos comandos.

Segundo, o frontmatter pode pré-autorizar 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 entra em vigor 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 claramente a consequência: reveja as skills do 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 versão pelo commit exato sempre que o mecanismo o permitir, porque uma tag pode ser movida e um branch muda por definição. Numa máquina com restrições, "disableSkillShellExecution": true nas definições substitui todas as substituições de comandos pelo texto literal [shell command execution disabled by policy] em vez de as executar, e, quando aplicado através de definições geridas, o utilizador não o pode substituir. 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 inclui no contexto do modelo tudo o que encontrar. Esse é o problema descrito em manter os segredos fora dos agentes que executa.

O que ler ao atualizar uma versão

• O diff de cada corpo SKILL.md, porque esse texto contém as instruções que o seu agente 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 próprios smoke tests na CI, a tag que está a fixar deve ter uma execução bem-sucedida associada.

Se um revisor não conseguir ler todo o diff em dez minutos, a skill cresceu demasiado. Divida-a. O mesmo se aplica à documentação do repositório que os seus agentes leem: mantenha as regras duradouras nos ficheiros descritos em a separação entre AGENTS.md e HUMAN.md e o raciocínio arquitetural num DESIGN.md escrito para agentes, mantendo as skills como procedimentos específicos.

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

Vários elementos subjacentes a uma skill podem mudar sem que ninguém a edite. Uma atualização do modelo altera a fiabilidade 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. Um harness de agente altera a forma como seleciona skills. Por isso, uma description que antes ganhava a correspondência pode deixar de ganhar.

É por isso que o teste de smoke test é fundamental nesta configuração. Execute o teste de cada skill segundo uma agenda e também a cada push. A Google executa semanalmente os seus trabalhos de avaliação contra toda a biblioteca por este motivo. Para uma equipa com dez skills, um cron job semanal num VPS pequeno é suficiente. É a única forma de saber que algo deixou de funcionar 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 de um harness que adicionar é uma aposta num único fornecedor. Escrever skills que sobrevivam à 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 referencie 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 marketplace de plugins faz o mesmo através de /plugin, com o pin declarado no .claude/settings.json do repositório consumidor. Ambos colocam a versão no histórico git, permitindo determinar que 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 marketplace de plugins do Claude Code, uma origem de plugin aceita ref para uma branch ou tag e sha para um commit exato; quando ambos estão presentes, sha tem prioridade. A origem do próprio marketplace aceita apenas ref. Prefira o pin para um commit, porque uma tag pode ser movida depois de a rever.

O que deve verificar um smoke test de uma skill?

Verifique algo estável. Execute a skill de forma não interativa contra um fixture que contenha uma falha conhecida. Depois, confirme que um identificador específico aparece no resultado, por exemplo, o id de uma regra que a skill deve reportar. Pedir 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 do repositório de outra equipa?

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

Uma skill partilhada funciona em agentes diferentes 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 ultrapassem a especificação são ignoradas ou rejeitadas noutros ambientes. Por isso, mantenha-as fora de qualquer skill que pretenda partilhar amplamente.