O conhecimento do agente é um problema de gatilho, não um problema de escrita

Eu coloquei tudo que um agente precisa para trabalhar em meu framework em um recurso MCP. Convenções, fluxos de trabalho, quais arquivos são gerados, de onde vêm os segredos. Era preciso, era completo e estava a uma chamada de distância.

O agente quase nunca leu isso.

Enquanto isso, eu estava fazendo esse trabalho manualmente. Parando no meio da tarefa. Corrigindo a mesma coisa pela quarta vez. Revisando novamente um trabalho em que eu havia parado de confiar três etapas antes. O conhecimento existia, era barato de buscar e nunca chegava. Passei um tempo assumindo que eu estava solicitando errado.

Eu não estava. Um recurso é passivo. Passivo significa que o agente tem que decidir olhar, e ele não decide olhar, porque nada lhe diz que há algo que vale a pena ser visto. Eu havia resolvido o conteúdo e enviado zero entrega.

Essa é a parte que eu tinha ao contrário. Os quatro lugares onde você pode colocar conhecimento para um agente não são quatro tipos de conteúdo. Eles são quatro condições de gatilho, e cada uma cobra de maneira diferente.

Quatro gatilhos, quatro preços

AGENTS.md dispara a cada turno. Incondicional. É também o único canal pelo qual você paga incondicionalmente, em cada solicitação, para sempre, quer este turno tenha algo a ver com isso ou não.

Ferramentas MCP disparam quando o agente quer agir. O gatilho é a intenção, que é confiável, porque o agente já sabe que precisa fazer algo. Você paga pelos esquemas que estão no contexto.

Habilidades disparam quando uma descrição corresponde à situação. Barato até que atinjam — a descrição está no contexto, o corpo não. A correspondência é todo o mecanismo, e é a única coisa que os outros canais não têm.

Documentos disparam quando o agente decide lê-los. O que é raro. Eficazmente gratuitos, e frequentemente valem exatamente isso.

Diga isso como um orçamento e o design se revela por si só. O canal sempre ativo é o mais caro, então ele contém o menos: um roteador que diz onde olhar, e as barreiras que devem se manter em cada turno. Nunca edite arquivos gerados. Leia segredos através do serviço. Isso é tudo. Todo o resto precisa ganhar seu peso correspondendo a algo.

Mau direcionamento

Todo fracasso que enfrentei foi o mesmo fracasso: conteúdo certo, gatilho errado.

Uma barreira em uma habilidade nunca dispara, porque "não edite arquivos gerados" não tem gatilho. Não há momento que corresponda a isso. O agente edita o arquivo, e a habilidade que teria impedido isso nunca acorda.

Um walkthrough em AGENTS.md cobra a cada turno por algo que importa duas vezes por mês. Você está pagando aluguel por um contexto que usa quase nunca.

O conhecimento do fluxo de trabalho em um recurso, ou em documentos, é o fracasso que já descrevi. Nada aponta para isso, então nada chega até lá.

Duas coisas que só aprendi ao enviar

Escreva contra o código em execução. Ao construir a habilidade de autenticação, descobri que os documentos nomeavam uma barreira de três maneiras diferentes e descreviam o mesmo cabeçalho de duas. O código tinha uma resposta. Uma habilidade escrita a partir de documentos distorcidos ensina a distorção, no exato momento em que o agente é mais propenso a agir sobre isso.

Instale antes de confiar. Da primeira vez que instalei meu próprio conjunto, a ferramenta rejeitou uma habilidade devido a um erro de formatação em sua descrição. Leria bem. Não analisou. Uma habilidade que não analisa não é uma habilidade mais fraca, não é habilidade nenhuma, e nada lhe diz isso.

Também vale a pena saber antes de se apoiar em qualquer uma dessas coisas: as habilidades precisam de uma etapa de instalação, e as pessoas pulam etapas de instalação. O arquivo sempre ativo e os documentos ainda precisam carregar qualquer um que nunca instala nada.

O ponto

O conhecimento do agente não é documentação. A documentação assume um leitor que vai procurar. Um agente não vai procurar, e começa do zero a cada sessão, então cada sessão paga novamente o custo de integração.

O que significa que a pergunta nunca é "eu escrevi isso?". É "o que dispara isso, e qual é o custo de disparar?". Se você errar isso, pode ter todas as respostas sentadas no repositório enquanto o agente adivinha na sua frente.

Isso surgiu da adição de um conjunto de habilidades ao tsdevstack, um framework TypeScript full-stack opinativo que gera sua infraestrutura a partir de um arquivo de configuração. O servidor MCP, o AGENTS.md e as habilidades vêm com ele.