Pular para o conteúdo principal
Os agentes personalizados estão em beta. O comportamento e as telas ainda podem mudar.

​
Skills & docs

Skills e docs são guias que já existem no seu repositório. A Kodus não copia esses arquivos: ela lê da branch de destino do pull request em toda revisão. Assim, edições nessa branch valem sem voltar às configurações, e um pull request não consegue mudar a regra que o avalia. Um guia também pode vir de outro repositório, como um repositório de regras compartilhado (veja De outro repositório mais abaixo). Scripts dentro de uma skill chegam ao agente como texto e nunca são executados.

​
Onde a Kodus encontra

Skills são detectadas em:
  • .claude/skills/*/SKILL.md
  • .claude/agents/*.md
  • .agents/skills/*/SKILL.md
  • .github/skills/*/SKILL.md
Um SKILL.md começa com um frontmatter YAML com name (letras minúsculas, dígitos e hífens, igual ao nome da pasta) e description. Uma skill sem eles aparece como “Not a valid skill”, com o motivo. O agente lê o SKILL.md (até 500 linhas, cerca de 5.000 tokens) e os arquivos ao lado dele, até uma pasta abaixo, como references/payments.md.
.claude/skills/ledger-rules/SKILL.md
Docs são sugeridos a partir de CONTRIBUTING.md, ARCHITECTURE.md, CONVENTIONS.md, STYLEGUIDE.md e docs/**/*.md (até 30). Você também pode adicionar qualquer caminho à mão: um arquivo com extensão é um doc; uma pasta (ou um SKILL.md dentro dela) é uma skill.

​
Vincular

Há dois lugares para vincular uma skill ou doc:
  • Na página do agente, em Files & knowledge → Skills & docs: Add skill or doc lista o que o agente pode seguir, ou use Add by path.
  • Na página Skills & docs (o link ao lado de Custom agents em What to review): todas as skills e docs cadastradas, com uma caixa de seleção para Main review e para cada agente. Vincular a Main review entrega o guia à revisão da própria Kody.
No nível global, a página Skills & docs só aceita caminhos digitados à mão. Cada repositório é lido separadamente; abra as configurações de um repositório para ver se cada caminho existe nele.

​
Citados por apontamentos descartados

Quando as revisões descartam apontamentos porque citam um arquivo que o agente não segue (“is not a guide linked to this review”), o Skills & docs do agente mostra esse arquivo em Cited by dropped findings, com quantos apontamentos foram descartados. Follow vincula o arquivo, deste repositório ou do repositório onde ele está. Só aparecem arquivos que existem.

​
De outro repositório

É comum o time manter as regras em um repositório e aplicá-las em vários. Escolha esse repositório em From ao adicionar um skill ou doc na página de um agente: os repositórios linkados aparecem primeiro, e Other repository… lista todos os repositórios conectados à Kodus (selecionados em Git settings). Se o repositório de regras não aparecer, conecte ele lá primeiro.
  • Um guia de outro repositório é lido na branch padrão desse repositório, ou na branch ou tag que você definir em Use a branch or tag instead. Uma branch ou tag por repositório. Um pull request nunca muda isso.
  • É só para custom agents. A review principal lê os guias do repositório revisado e as instruções para agentes de código dele, não os de outro repositório, por isso a página Skills & docs não oferece Main review para ele.
  • Ele carrega como um guia do repositório revisado, em toda review, sem sandbox e mesmo que a mudança não toque o outro repositório.
  • O agente cita o guia como owner/repo:caminho, e o comentário traz o link do arquivo.
  • Quando o repositório de regras é privado e o revisado é público, o comentário cita o arquivo sem copiar o trecho.
Quando as instruções de um agente citam um repositório linkado do qual ele não segue nada, a página do agente avisa e oferece Browse its rules. Quando citam um arquivo de regra (.md, .mdc, .mdx) que o agente não segue, a página oferece Follow it para esse arquivo, no repositório onde as instruções o colocam. Um doc seguido vai inteiro para o prompt do agente: ele deixa de depender de decidir ler o arquivo, e os findings podem citá-lo.
Um arquivo marcado como Also a Kody Rules source já alimenta as Kody Rules. Vinculá-lo também a um agente pode fazer a mesma regra comentar duas vezes.

​
Orçamentos

Por agente, e para a revisão principal: A página Skills & docs avisa quando um agente ou a revisão principal passa de um limite. Na revisão, os docs que passam do orçamento são cortados ou pulados, e a revisão registra um aviso.

​
Como os apontamentos usam esses guias

Um apontamento de convenção precisa citar a regra que aplica. A Kodus confere a citação no guia como ele está na branch de destino e descarta o apontamento quando a citação não está lá. O comentário publicado cita a regra:
Uma regra de outro repositório é citada como owner/repo:caminho, com link para o arquivo na branch de onde foi lida.

​
Plugins (MCP)

Os agentes podem consultar os plugins instalados no seu workspace: um gerenciador de tarefas, uma wiki, o monitoramento. Em Tools → Plugins, ligue um plugin para o agente e mantenha Use every tool, ou use Customize para escolher as ferramentas. Só ferramentas de leitura são oferecidas; ferramentas de escrita nunca são. Um plugin que marca as ferramentas como somente leitura é levado ao pé da letra. Para um que não marca, a ferramenta só entra quando o nome tem um verbo de leitura (get, list, search, read, find…) e nenhum verbo de escrita. Uma revisão nunca cria um ticket nem posta uma mensagem em nome do seu time. O agente consulta um plugin quando a mudança aponta para algo registrado ali, como um ticket na descrição do pull request, e cita o que encontrou. Veja Plugins para instalar um.

​
CLIs do time

Um agente pode rodar até 3 ferramentas de linha de comando do seu time: um detector de código duplicado, um verificador de schema, um linter interno. As CLIs rodam só no sandbox isolado da E2B, dentro do checkout do repositório. Em qualquer outro sandbox a CLI não é instalada e o agente roda sem ela. Em Tools → CLIs, clique em Add CLI: Regras de instalação. Instaladores aceitos: npm, pnpm, yarn, pip, pip3, pipx, uv, go, cargo. Todo pacote precisa estar fixado (tool@1.2.3, tool==1.2.3 ou tool@sha256:…). Tags como @latest, faixas de versão, URLs, fontes Git, caminhos locais e sintaxe de shell são recusados.
Como as chamadas rodam. O agente passa argumentos, nunca um comando de shell: pipes, redirecionamentos, globs e variáveis são passados literalmente. Uma chamada que não começa com um prefixo permitido é recusada. Cada CLI roda com seu próprio usuário, com timeout, um diretório temporário privado e arquivos legíveis só por esse usuário; a saída é limitada, e tudo o que ela iniciou ou gravou em diretórios temporários é removido depois da chamada. Cada etapa de uma CLI roda como root pelo provedor do sandbox, nunca pelo usuário com que a revisão roda: esse usuário perde qualquer forma de virar root (inclusive sudo) antes de o repositório ser baixado, então código do pull request não alcança o processo nem os arquivos de uma CLI. Um sandbox em que isso não pôde ser confirmado não roda nenhuma CLI. Comandos bloqueados. Numa CLI com secrets, o Kodus recusa, ao salvar e na execução, prefixos e argumentos que listam o ambiente (printenv, env, set, export, declare, qualquer coisa em /proc), comandos comuns que imprimem tokens (auth token, auth status --show-token, auth:token, config get, configure get, print-access-token, get-access-token), um shell ou interpretador como binário (bash, node, python, npx, …) e argumentos que citam um dos seus secrets como $NOME ou ${NOME}. Os argumentos nunca passam por um shell, então o próprio Kodus nunca os expande. Rede. A allowlist vale pelo nome do host. As conexões HTTPS da CLI passam por um proxy que só encaminha uma conexão quando o nome de servidor pedido está na lista (nome exato, sem subdomínios) e que resolve esse nome por conta própria, recusando endereços privados e internos. A CLI não tem outro acesso à rede: nem DNS, nem HTTP sem TLS, nem outras portas. Um host permitido ainda recebe o que a CLI enviar, credenciais incluídas, e a rede não distingue leitura de escrita. Use tokens somente leitura, com o menor privilégio possível, e permita só hosts em que você confia. Como os secrets são guardados. Um secret é criptografado ao salvar (AES-256-GCM, vinculado ao agente, à CLI e ao nome da variável) e nunca volta para o navegador, que mostra Stored · hidden. Ele fica vinculado à CLI para a qual foi salvo, naquele nível de configuração: qualquer mudança na CLI (nome, instalação, binário, prefixos permitidos, domínios permitidos, Runs project code ou os nomes dos seus secrets) pede todos os secrets de novo, ao salvar e no Try it. Só as notas de uso e o timeout mudam sem isso. Um secret guardado que não pode mais ser lido também precisa ser digitado de novo. O Try it usa só os secrets guardados no nível que você está editando, nunca os herdados. Um secret chega só ao processo daquela CLI, nunca à instalação, às outras CLIs ou ao prompt do agente. Na saída da CLI, todo secret é trocado por ***, também quando impresso em base64, codificado em URL, em hex ou escapado em JSON, antes que o agente, o Try it, um comentário no pull request ou um log o vejam. O mascaramento não reconhece toda transformação (um valor partido ou parcial), e é por isso que os comandos acima são bloqueados. Quando um apontamento vem de uma CLI, o comentário mostra as linhas da saída que citam o arquivo:
Se a instalação falha, o agente roda sem aquela CLI e a execução registra o aviso. O Try it mostra isso em Warnings.

​
Regras do ast-grep

Em Tools → Advanced → Structural search (ast-grep rules), dê ao agente regras do ast-grep, de um destes jeitos:
  • Inline: o YAML da regra. Separe várias regras com ---. Cada uma precisa de id e rule.
  • Um arquivo de regras: uma única linha com o caminho de um arquivo .yml ou .yaml do repositório, lido da branch de destino do pull request.
As regras rodam sobre os arquivos alterados do pull request. Um match é prova: um apontamento que cita uma regra que bateu naquele arquivo durante a execução pula a checagem de citação e a verificação pelo modelo. As regras têm limite de 64.000 bytes. A dica do campo lista as regras encontradas e aponta regras sem id ou sem rule. O agente também tem busca estrutural avulsa pelo repositório, mesmo sem nenhuma regra configurada.

​
Veja também

Agentes Personalizados

Níveis, a página do agente, Try it e como os agentes rodam numa revisão.

Código duplicado com jscpd

Um agente completo com uma CLI do time.