GitHub Copilot

Fornecedor: GitHub / Microsoft Nome de instalação: github-copilot Status: GA Configuração nativa: <project>/.github/copilot-instructions.md

InstalaçãoCopy Anchor Link

apothem install --harness github-copilot --project /path/to/project

O adaptador deriva o arquivo de instruções do projeto a partir do seu perfil compartilhado e da superfície compartilhada de regras e governança do Apothem, grava os auxiliares do Apothem como perfis de auxiliar do Copilot no projeto (consulte Perfis de auxiliar) e registra dois hooks (consulte Hooks).

Ele também grava as skills do Apothem, e as regras e templates que elas citam, no seu diretório pessoal, antes de tocar no projeto (consulte Arquivos fora do projeto).

Arquivos gravados:

• <project>/.github/copilot-instructions.md, o arquivo de instruções.
• <project>/.github/agents/<name>.agent.md para cada auxiliar do Apothem, no projeto.
• <project>/.github/hooks/apothem.json, o arquivo de hook, no projeto. Seus próprios arquivos de hook nessa pasta não são tocados.
• <project>/.apothem/support/github-copilot/hooks/, os scripts de hook, no projeto.
• ~/.agents/skills/<name>/SKILL.md para cada skill e comando do Apothem, no seu diretório pessoal.
• ~/.config/apothem/rules/ e ~/.config/apothem/templates/, no seu diretório pessoal.

Arquivos fora do projetoCopy Anchor Link

A instalação também grava as skills do Apothem no seu diretório pessoal, antes de alterar qualquer coisa no projeto:

Essas pastas são compartilhadas. Elas não são privadas do projeto:

• Todo projeto em que você instala github-copilot, e toda outra instalação do Apothem que nomeia a pasta, usa a mesma cópia e grava os mesmos arquivos, então a ordem em que você instala não importa. Várias outras ferramentas também leem ~/.agents/skills/; o registro de harnesses as lista.
• --project escolhe o arquivo de instruções a gravar e a qual projeto a instalação pertence. Ele não muda para onde vão as skills.
• A instalação não adiciona nenhum arquivo de skill ou de regra ao seu repositório. O projeto recebe o arquivo de instruções, os arquivos de perfil de auxiliar em .github/agents/, o arquivo de hook .github/hooks/apothem.json, além da pasta .apothem/ que toda instalação de projeto cria, que também guarda os scripts de hook.
• As pastas do diretório pessoal são gravadas primeiro. Se isso falhar, por exemplo porque uma pasta no caminho é um link que sai do seu diretório pessoal (um link que permanece dentro dele é seguido) ou não pode ser gravada, a instalação para com o erro antes que qualquer coisa no projeto mude.
• Uma pasta de skill com o nome de uma skill do Apothem que o Apothem não gravou é deixada intacta, e a instalação exibe um aviso que a nomeia. Renomeie-a ou mova-a e depois execute apothem update. apothem verify falha enquanto esse nome estiver ocupado.
• Os arquivos somam alguns megabytes.

A instalação exibe uma nota que nomeia as pastas que ela grava fora de --project, e --dry-run as lista.

Perfis de auxiliarCopy Anchor Link

O Copilot lê um perfil de auxiliar de <project>/.github/agents/<name>.agent.md, conforme a referência do GitHub para esses perfis. A instalação grava um arquivo por auxiliar do Apothem nessa pasta. Ela instala apenas para o projeto e não grava nenhuma pasta ~/.copilot/agents/.

Cada arquivo mantém as instruções do auxiliar inalteradas e traz estas chaves de frontmatter:

A chave tools do Copilot é uma lista de permissões de aliases, e ele não tem nenhuma chave que negue uma ferramenta. Assim, as ferramentas permitidas e as ferramentas negadas do auxiliar são combinadas em uma única lista:

O Copilot tem mais um alias, aquele que permite a um auxiliar iniciar outros auxiliares; nenhum auxiliar do Apothem tem permissão para fazer isso, então ele nunca é gravado. Um alias é deixado de fora quando o auxiliar nega qualquer ferramenta que ele cobre, porque o alias permitiria ao auxiliar usar essa ferramenta. Uma ferramenta sem alias (por exemplo Monitor) é deixada de fora. Uma ferramenta com um padrão, como Bash(git status), não tem forma de alias: como ferramenta permitida ela é deixada de fora, e como ferramenta negada ela nega a ferramenta inteira. Um auxiliar que não pode editar arquivos mantém esse limite: ele nunca recebe edit. Se toda ferramenta da lista de um auxiliar for deixada de fora, o arquivo diz tools: [], o que não dá nenhuma ferramenta ao auxiliar, em vez de omitir a chave, o que lhe daria todas as ferramentas.

A instalação não grava nenhuma chave model, então um auxiliar usa o modelo padrão, nem nenhuma das outras chaves que o Copilot documenta (target, disable-model-invocation, user-invocable, mcp-servers, metadata), um limite de turnos ou as chaves version, updated e portability do Apothem.

Pontos a saber:

• .github/agents/ faz parte do seu repositório. Os colegas de equipe e o serviço de codificação na nuvem do Copilot leem os mesmos arquivos, então faça commit deles com o projeto ou liste .github/agents/ no .gitignore; o Apothem não escolhe por você.
• O serviço de codificação na nuvem não respeita os aliases web e todo. O alias web cobre tanto a busca na web quanto a busca de páginas, então citation-auditor, fact-checker e research-scout podem ler e pesquisar arquivos ali, mas não podem pesquisar na web nem buscar páginas.
• A Copilot CLI também lê o .claude/agents/ do repositório, mas não ~/.claude/agents/, então a instalação do Claude Code não chega ao Copilot.
• Um arquivo seu nomeado como um auxiliar do Apothem (<name>.agent.md) é salvo em ~/.apothem/backups/ e depois substituído. A desinstalação não o restaura. Arquivos com outros nomes nunca são tocados. A documentação do Copilot não diz o que acontece quando a pasta contém tanto <name>.md quanto <name>.agent.md.
• O Apothem não confirmou se o Copilot prefere .github/agents/ ou .claude/agents/ para um mesmo nome, nem como o serviço de codificação na nuvem e o VS Code tratam uma chave de frontmatter que eles não listam.

HooksCopy Anchor Link

O Copilot executa hooks a partir de arquivos JSON em <project>/.github/hooks/, conforme a referência de hooks do Copilot. A instalação grava um arquivo ali, apothem.json (versão 1), com dois hooks:

Ambos adicionam contexto para o modelo. Nenhum deles bloqueia uma chamada de ferramenta ou uma sessão.

O Apothem não registra nenhuma proteção preToolUse no Copilot. Para preToolUse o Copilot lê apenas campos de permissão e uma entrada de ferramenta reescrita, nunca additionalContext (o campo pelo qual as proteções do Apothem se comunicam). Uma proteção registrada ali custaria o início de um processo a cada chamada de ferramenta e não entregaria nada, então as proteções de gravação, edição e shell, a verificação de AskUserQuestion e o protocolo de fim de sessão permanecem nas ferramentas que os entregam. Os hooks usam os nomes de evento em camelCase do Copilot, porque a referência lista os campos de saída para esses; se o Copilot lê additionalContext de um evento em PascalCase não está documentado.

Para onde vão os arquivos

Cada hook tem um comando bash e um comando powershell. Eles executam o mesmo despachante; o powershell tem um operador de chamada (&) na frente, do qual o PowerShell precisa antes de um caminho de programa entre aspas. Um comando bash tem esta aparência, com o seu interpretador e o caminho do seu projeto no lugar dos dois caminhos:

"/path/to/python" "/path/to/project/.apothem/support/github-copilot/hooks/dispatch.py" --contract copilot sessionStart

--contract copilot faz o despachante ler a entrada em camelCase do Copilot e imprimir {"additionalContext": ...}, que é o que o Copilot lê para esses dois eventos.

Faça commit com cuidado, e o agente na nuvem. .github/hooks/ faz parte do seu repositório, e o serviço de codificação na nuvem do Copilot o lê. Os comandos nomeiam o interpretador que o Apothem encontrou quando foi executado e o caminho absoluto do projeto, e os scripts estão em .apothem/, que o snippet de .gitignore de um projeto ignora. Em qualquer outra máquina, e no serviço na nuvem (que executa apenas o comando bash), o comando não encontra nada para executar. O Copilot registra a falha e a execução continua, porque um hook sessionStart ou postToolUse com falha não bloqueia. Adicione .github/hooks/apothem.json ao .gitignore, ou faça commit dele somente para uma equipe que compartilha o mesmo layout. A instalação não edita o .gitignore e exibe isso como uma nota.

Seus próprios hooks. Arquivos de hook seus em .github/hooks/ nunca são lidos nem alterados. Um hook que você adiciona ao próprio apothem.json permanece: uma atualização e uma desinstalação substituem ou removem apenas as entradas cujo comando executa o despachante do Apothem (.apothem/support/github-copilot/hooks/dispatch.py com --contract copilot, seja qual for o caminho de projeto sob o qual foi gravada). Um hook seu que apenas compartilha o nome, ou que executa python -m apothem.conformity.gate, nunca é tomado pelo do Apothem. Um arquivo que não é JSON válido é salvo em ~/.apothem/backups/ e substituído.

Caminhos que o shell leria errado. Um caminho de projeto ou de interpretador que contém $, um acento grave, aspas duplas ou uma barra invertida é recusado antes que qualquer coisa seja gravada: dentro do comando entre aspas ele executaria um arquivo diferente, ou quebraria o JSON no qual o comando é gravado. O erro nomeia o caminho; mova ou renomeie o projeto e execute a instalação novamente. Um espaço ou um apóstrofo em um caminho não causa problema.

Desativando os hooks. Defina APOTHEM_HOOKS_DISABLE=1 no ambiente em que o Copilot é executado para silenciar os hooks do Apothem, ou defina "disableAllHooks": true em apothem.json, o que ignora esse único arquivo.

O contrato de hook Local mais antigo do VS Code (eventos com os campos command, windows, linux e osx) é um formato diferente que um arquivo da versão 1 não tem como alvo.

Mapeamento do perfil para a configuração nativaCopy Anchor Link

O adaptador lê o perfil compartilhado do Apothem e renderiza o arquivo de instruções do Copilot para todo o repositório a cada execução de apothem install ou apothem update. O perfil compartilhado é a fonte da verdade; as edições locais do projeto no arquivo gerado recebem backup antes que a próxima sincronização substitua o conteúdo gerenciado pelo Apothem.

Dentro do bloco do Apothem, a seção renderizada a partir do seu perfil (operador, preferências, regras personalizadas, comportamentos ativados por opção, nomes de servidores MCP) vem primeiro, antes do texto de governança compartilhado. O GitHub observa que arquivos de instruções mais curtos têm mais probabilidade de ser processados por inteiro pela revisão de código (Personalização da revisão de código), então a parte específica para você abre o arquivo.

Notas de compatibilidadeCopy Anchor Link

O GitHub Copilot não expõe um caminho de instruções globais do usuário baseado em arquivos para que este adaptador gerencie. O Apothem mira o arquivo de instruções com escopo de projeto documentado e deixa as configurações de usuário no nível da IDE sob a propriedade do operador. Ele grava um arquivo de hook, .github/hooks/apothem.json, e nenhum outro arquivo em .github/hooks/.

Dentro do repositório do Apothem, .github/copilot-instructions.md é uma voz entre as superfícies de instruções de assistente desse repositório. Em um checkout desse repositório, a verificação de coerência multissuperfície do conformity gate compara as afirmações compartilhadas em AGENTS.md, CLAUDE.md e .github/copilot-instructions.md. Ela relata uma afirmação compartilhada que um dos três arquivos omite e um arquivo que contradiz uma afirmação feita por AGENTS.md. A verificação não lê o arquivo de instruções que o Apothem grava no seu projeto. O gate é consultivo por padrão: ele relata os achados e encerra com 0.

O GitHub Copilot lista ~/.agents/skills/ entre seus locais de skills pessoais, então as skills que a instalação grava estão na sua máquina para o Copilot carregar. As superfícies que rodam no GitHub, o serviço de codificação na nuvem e a revisão de código, rodam em outro lugar e não veem o seu diretório pessoal, e é por isso que o arquivo de instruções traz as próprias disciplinas. O Apothem não confirmou como o Copilot trata uma chave de cabeçalho de SKILL.md que ele não lista; as skills trazem user-invocable, disable-model-invocation, allowed-tools, argument-hint e um mapa metadata.

VerificaçãoCopy Anchor Link

apothem verify --harness github-copilot --project /path/to/project

O comando verify confirma que:

1. A configuração nativa existe no caminho esperado.
2. Cada destino gerenciado existe, incluindo a pasta .github/agents/; os arquivos gerenciados não estão vazios, e as configurações JSON ou YAML podem ser analisadas. Adicione --profile PATH para também confirmar que os arquivos instalados correspondem a esse perfil. Para .github/agents/ a verificação é que a pasta existe, não que cada arquivo de auxiliar esteja nela; o comando apothem diff --harness github-copilot --project /path/to/project lista os arquivos de auxiliar que estão ausentes ou desatualizados. O arquivo de hook .github/hooks/apothem.json deve existir, não estar vazio, ser analisado como JSON e conter uma entrada que executa o despachante do Apothem, e os scripts de hook devem estar em .apothem/support/github-copilot/hooks/. A verificação não executa os hooks.
3. Toda pasta de skill do Apothem está no lugar com um SKILL.md, seja qual for a instalação que a gravou, e nenhuma pasta de skill com um nome do Apothem pertence a algo que o Apothem não gravou. Uma verificação com falha nomeia as pastas ausentes ou alheias.
4. A rotina de verificação específica do adaptador informa sucesso.

AtualizaçãoCopy Anchor Link

apothem update --harness github-copilot --project /path/to/project

Deriva novamente o arquivo de instruções do projeto a partir do estado atual do perfil compartilhado.

A atualização também regrava qualquer pasta de skill cujos arquivos difiram dos atuais. Se você instalou com uma versão anterior que não gravava skills, a atualização as adiciona. Ela regrava os arquivos de perfil de auxiliar que diferem dos atuais e adiciona os que estiverem ausentes. Ela também atualiza os scripts de hook e os hooks do Apothem em .github/hooks/apothem.json, mantendo qualquer hook seu nesse arquivo.

DesinstalaçãoCopy Anchor Link

apothem uninstall --harness github-copilot --project /path/to/project

Remove o bloco do Apothem de <project>/.github/copilot-instructions.md e mantém qualquer texto fora dele. O arquivo só é excluído quando nada mais resta nele. Antes da alteração, uma cópia do arquivo com carimbo de data e hora é salva sob ~/.apothem/backups/. O YAML do perfil compartilhado e o motor do Apothem não são afetados.

A desinstalação também remove os arquivos de perfil de auxiliar que gravou em <project>/.github/agents/ e mantém qualquer outro arquivo ali; a pasta é removida quando fica vazia. Ela remove os hooks do Apothem de <project>/.github/hooks/apothem.json, reconhecendo-os pelo caminho do despachante no seu comando, então funciona sem um registro de instalação, e mantém qualquer hook seu nesse arquivo. O arquivo é excluído quando nada mais resta nele, e seus outros arquivos de hook não são tocados. Se o arquivo tiver comentários que a desinstalação não consegue ler, ela deixa o arquivo como está e informa os hooks como ignorados, com o motivo; remova as entradas do Apothem manualmente. Os scripts de hook em <project>/.apothem/support/github-copilot/hooks/ também são removidos. Ela remove as pastas de skill que gravou em ~/.agents/skills/ e as regras e templates em ~/.config/apothem/, mas somente quando nenhuma outra instalação do Apothem ainda as usa. Outro projeto, ou outra ferramenta que compartilha a pasta, pode usá-las. Nesse caso a desinstalação mantém as pastas, exibe qual instalação as usa, e a última desinstalação as remove. Os arquivos que você adicionou a essas pastas permanecem, e uma pasta que fica vazia é removida. Cada pasta recebe backup em ~/.apothem/backups/ antes de ser removida.

Conformity gateCopy Anchor Link

python -m apothem.conformity.gate --all .

A execução com --all cobre os validadores independentes. Ela não executa a verificação de coerência multissuperfície descrita em Notas de compatibilidade. Para executar essa verificação pelo nome em um checkout:

python -m apothem.conformity.gate --check multi-surface-coherence-grep AGENTS.md

Solução de problemasCopy Anchor Link

Ajustes de configuraçãoCopy Anchor Link

Veja tambémCopy Anchor Link

• Todos os harnesses — o catálogo completo de ferramentas suportadas
• Guia de instalação — instale o Apothem neste harness
• Referência de apothem harnesses — liste e inspecione adaptadores pela CLI