Uso a mesma montagem em todo projeto onde um agente faz trabalho de verdade. Já a usei em três bases de código bem diferentes: um produto de consumo, um pipeline de desenvolvimento de negócios e um rastreador de dados pessoais. Domínios diferentes, o mesmo esqueleto. Tudo se organiza em torno de dois diretórios, skills/ e resources/, e de uma decisão: o agente recebe permissões totais no repositório.
A ideia central
Um agente vale apenas o que ele consegue ver e o que tem permissão de fazer. A maioria das montagens falha em um dos dois pontos. Ou deixam o conhecimento do domínio na cabeça de uma pessoa, ou embrulham cada ação em um pedido de confirmação até o agente não valer mais a pena. Este método trata os dois: escreva o conhecimento onde o agente o lê e depois saia da frente.
skills/
Uma pasta por tarefa que o agente executa. Cada pasta tem um SKILL.md e, quando o trabalho tem um núcleo determinístico, uma pasta scripts/.
SKILL.md abre com um cabeçalho YAML contendo um name e uma description. A descrição é uma lista de gatilhos em linguagem natural, as frases que eu de fato digito: "registre meu almoço", "ache leads para esta campanha", "mostre o que eu comi esta semana". O agente casa com essas frases e carrega a skill por conta própria. Nunca chamo uma skill pelo nome.
O corpo é um procedimento curto: reunir as entradas, fazer a coisa, dar o retorno. O julgamento fica em prosa. Tudo que é mecânico (uma inserção em banco, uma chamada de API, um scraping de dados em centenas de linhas) vai para um script que o agente executa, para que rode do mesmo jeito toda vez e nunca despeje dados brutos na janela de contexto.
As skills vêm em camadas, e cada uma diz onde se encaixa. Uma skill da camada de escrita registra algo; uma skill de leitura ou diagnóstico a relê e a interpreta. Onde um projeto tem uma sequência natural, as camadas formam um pipeline fixo que o agente segue em ordem, e cada skill anota sua posição nesse pipeline.
resources/
Referência compartilhada que não está presa a nenhuma skill específica. Apenas Markdown. Uma skill lê o arquivo relevante como contexto antes de agir. Conteúdo típico:
- Esquema — o formato dos dados que as skills leem e escrevem.
- Perfil — meus objetivos, linhas de base e restrições, para que o agente avalie os resultados contra o alvo certo em vez de um genérico.
- Vocabulário — os nomes canônicos das coisas, para que os registros fiquem consistentes entre execuções.
- Modelo do domínio e playbooks — como o sistema subjacente funciona e a abordagem passo a passo para as fases do trabalho.
A separação é o ponto. Skills são verbos, resources são substantivos. Uma skill diz ao agente como fazer algo; um resource diz o que é verdade. Uma base de código maior pode manter esse mesmo conhecimento em um documento de orientação de alto nível e um conjunto de arquivos de referência em vez de uma pasta resources/, mas o papel é idêntico.
O resto do esqueleto
- Um documento de orientação. Algo que permita ao agente raciocinar sobre o sistema sem ler cada arquivo. Para uma base de código grande, é um mapa longo das partes móveis e de como elas se conectam. Para uma pequena, é a ordem do pipeline e uma tabela apontando para as skills, mais as frases de gatilho em cada
SKILL.md, o que mantém o repositório autodescritivo. - Configuração de agente versionada. Listas de permissões, plugins habilitados e servidores MCP ficam no repositório, não na montagem local de alguém.
- Estado que o agente possui diretamente. Um arquivo de banco de dados local, diretórios de dados simples, pastas de saída de scripts. Nenhuma camada de serviço entre o agente e os dados.
- Um front-end de bot quando eu quiser um. Um chatbot ou um webhook que invoca as mesmas skills que a CLI, para que haja uma implementação, não duas.
- Pastas de avaliação e iteração. Onde testo e refino o prompt de uma skill contra casos salvos antes de confiar nela.
Conexões opcionais
Plugins e servidores MCP não fazem parte do esqueleto central, mas ampliam o que o agente consegue alcançar sem eu escrever um script para cada integração. Eles são declarados na configuração versionada para que um clone novo os pegue. Os que eu mais uso:
- Plugin da Vercel — deploys, variáveis de ambiente e status de deploy, para que o agente consiga publicar uma mudança e confirmar que ela foi ao ar.
- Plugin do GitHub — pull requests, issues e revisões de dentro da sessão em vez de recorrer ao
gite ao navegador. - Gateway MCP do Docker — um único endpoint na frente de um conjunto de ferramentas em contêiner (automação de navegador, busca, pesquisa), para que o agente tenha um conjunto amplo de ferramentas sem uma instalação separada para cada uma.
A regra é a mesma das skills: uma conexão só merece seu lugar se remover uma fricção real. Todo o resto fica de fora para que a lista de ferramentas continue legível.
Permissões totais
O agente, quase sempre um modelo Claude, roda sem restrições dentro do repositório. Ele lê, escreve, roda scripts e faz commit sem pedir a cada vez.
É uma troca deliberada, e funciona por causa de onde as proteções de fato ficam:
- O repositório é o raio de alcance. Cada projeto é limitado a um domínio. Um agente em um projeto não consegue alcançar os dados de outro projeto.
- O Git é o botão de desfazer. Toda mudança é um diff que eu posso ler e reverter.
- Os backups rodam por temporizador. Tudo que não é código-fonte, como um banco de dados local, se copia em um cronograma e mantém um histórico rotativo.
- "Sem necessidade de confirmação" é escrito por skill, não presumido. Uma skill de registro diz para escrever direto. Uma skill que envia e-mail ou gasta dinheiro diz o contrário. A postura padrão é rápida; as exceções são explícitas.
Pedidos de confirmação a cada ação só treinam você a clicar sem ler. Prefiro tornar o ambiente seguro para agir rápido e gastar minha atenção lendo diffs.
Por que é portátil
Os domínios em que usei isso não têm nada em comum. O método ainda assim transita entre eles porque não é sobre o domínio. É um jeito de dividir um sistema no que o agente faz (skills/), no que o agente precisa saber (resources/ e o documento de orientação), no que ele tem permissão de tocar (a configuração versionada) e onde os dados moram (arquivos que ele possui). Comece um projeto novo, crie esses quatro, e o agente é produtivo no primeiro dia.