Skills

Uma skill é uma capacidade focada e reutilizável que seu agente de codificação por IA invoca em um ponto específico do fluxo de trabalho de desenvolvimento. O Archgate fornece cinco skills como parte dos plugins de editor, e juntas elas transformam os ADRs armazenados em .archgate/ em um loop de governança fechado: as decisões guiam o código antes de ele ser escrito, o código é verificado contra elas depois e novas lições realimentam as decisões.

As skills normalmente são invocadas pelo agente developer automaticamente — raramente você as chama manualmente. Cada uma é responsável por uma parte do fluxo de trabalho:

UNDERSTAND → PLAN → WRITE → VALIDATE → CAPTURE
                             reviewer   lessons-learned

onboard roda uma vez no início de um projeto para criar os ADRs iniciais. adr-author é a camada de autoria autoritativa para a qual toda outra skill delega sempre que um ADR precisa ser criado ou editado. cli-reference é um auxiliar interno que carrega a documentação canônica da CLI sob demanda.

As cinco skills

reviewer — a etapa VALIDATE

Depois que o código é escrito, a skill reviewer o valida contra os ADRs do projeto. Ela reúne tudo em uma única chamada com archgate review-context --run-checks (arquivos alterados agrupados por domínio, os briefings de ADR aplicáveis e os resultados das verificações automatizadas) e, em seguida, lança um sub-agente focado por domínio afetado para verificar cada um isoladamente. Se as verificações automatizadas já falham, ela bloqueia imediatamente. Violações de ADR são bloqueadores rígidos; avisos são sempre apresentados ao usuário, mas não bloqueiam. Rodar cada domínio em seu próprio sub-agente mantém o contexto do agente pai enxuto mesmo quando muitos arquivos mudaram.

lessons-learned — a etapa CAPTURE

A skill lessons-learned é a última etapa do fluxo de trabalho, depois que as verificações e o reviewer confirmam a conformidade. Ela lê a transcrição completa da sessão via archgate session-context (recuperando o contexto que a compactação pode ter descartado) e o panorama atual de governança via archgate review-context, identifica padrões e erros recorrentes e propõe novos ADRs ou extensões a existentes — ou registra notas operacionais na memória do projeto. Ela é deliberadamente conservadora: só propõe regras para padrões claros e repetidos, sustentados por evidência concreta de código. Este é o movimento de aprendizado do loop que transforma erros em regras permanentes.

adr-author — a única camada de autoria

A skill adr-author cria e edita ADRs para corresponder à estrutura, ao tom e à profundidade das decisões existentes do projeto. Ela impõe as seis seções obrigatórias, a ordem dos campos do frontmatter, os prefixos de ID por domínio e o arquivo de regras complementar quando a aplicação automatizada se justifica. Ela é o único lugar que escreve arquivos de ADR — onboard e lessons-learned delegam a ela em vez de tocar nos ADRs diretamente, o que mantém cada decisão do projeto em um padrão consistente.

onboard — configuração inicial

A skill onboard inicializa um projeto na governança: ela verifica a CLI, roda archgate init, explora a base de código com sub-agentes em paralelo, entrevista você sobre suas convenções, propõe um backlog de ADR e escreve cada ADR aprovado em paralelo antes de entregar um resumo de governança. Rode-a uma vez ao configurar o Archgate e novamente mais tarde para estender a governança a novos domínios ou auditar ADRs existentes.

cli-reference — carregador de referência interno

A skill cli-reference é invocada por outras skills e pelo agente, não por você. Como a CLI archgate é mais recente do que a maioria dos cortes de treinamento dos modelos, os agentes não devem adivinhar a sintaxe dos comandos nem a API de regras. Esta skill busca a documentação canônica da CLI e retorna apenas a seção que o chamador pediu (comandos da CLI, autoria de regras ou formato de ADR), de modo que os agentes trabalhem a partir de referência autoritativa, e não da memória.

Como as skills compõem o loop

As skills mapeiam diretamente nos três movimentos do loop de governança:

Movimento	Skill(s)	O que acontece
Prevenção	onboard, adr-author	Os ADRs são criados e mantidos atualizados; o agente os lê
Detecção	reviewer	O código é validado contra os ADRs depois de escrito
Aprendizado	lessons-learned → adr-author	Novos padrões são capturados de volta nos ADRs

cli-reference é o tecido conectivo: qualquer skill que precise de detalhes exatos de comando ou de API o carrega primeiro.

Nomenclatura

Alguns marketplaces de plugins exibem as skills de validação e captura com nomes de exibição alternativos, mas seu comportamento é idêntico em todos os editores. Esta documentação usa os nomes canônicos das skills: reviewer, lessons-learned, adr-author, onboard e cli-reference.

Conceitos relacionados

Visão geral das skills A referência completa de todas as cinco skills.

Agentes Os agentes developer e planner que invocam as skills.

O Loop de Governança O ciclo que as skills orquestram.

Plugins Como as skills são distribuídas ao seu editor.