Todo sistema de agentes enfrenta o mesmo trade-off desconfortável. Você deseja uma base de conhecimento profunda e bem organizada que sobreviva a revisões de código e ao histórico do git. Mas você também precisa que o runtime seja rápido e mantenha o foco. Essas duas necessidades trabalham uma contra a outra. Quanto mais instruções você preserva, mais tentador se torna despejar todas elas no prompt e torcer para que tudo dê certo. Essa esperança custa caro.
No ecossistema Agent Project Context, essa tensão se divide claramente em duas camadas. O APC cuida da durabilidade. O APX cuida da velocidade. Entender como eles interagem — e por que o APX se recusa a pré-carregar cada definição de skill — revela mais sobre engenharia de prompt do que a maioria dos guias de otimização dirá.
O Arquivo e o Motor
O trabalho do APC é a permanência. Ele armazena arquivos de skills reutilizáveis em .apc/skills/ como documentos Markdown simples. Como esses arquivos vivem dentro do seu repositório, eles acompanham o controle de versão. Você pode abrir um pull request que altera um procedimento de implantação. Você pode fazer o diff de um rollback de política de segurança de seis semanas atrás. Você pode auditar exatamente o que o agente deveria saber e quando. Essa capacidade de revisão é crucial quando uma implantação ruim entra em produção ou quando um auditor de conformidade começa a fazer perguntas.
O APX, por outro lado, vive o momento. Ele gerencia a conversa real entre você e o modelo. Seu objetivo não é arquivar conhecimento, mas usá-lo com precisão. Quando o APX trata as skills como bagagem permanente, todo o sistema desacelera. A janela de contexto se enche. Os custos de tokens aumentam. Pior ainda, a atenção do modelo se dispersa em instruções que não têm nada a ver com a requisição atual.
É por isso que o corpo das skills é carregado sob demanda.
O Verdadeiro Custo de um Prompt Inchado
A maioria das equipes entende que tokens custam dinheiro. Poucas equipes percebem que tokens irrelevantes custam precisão.
Quando o APX injeta cada skill disponível em cada turno, o prompt torna-se ruidoso. O modelo recebe o runbook de implantação, o guia de segurança, a referência de estilo de API, o checklist de testes e o FAQ de onboarding, tudo de uma vez. Mesmo com uma janela de contexto grande, a qualidade do raciocínio degrada quando o modelo precisa primeiro filtrar o ruído para encontrar o sinal. Ele pode se prender a um requisito de segurança destinado a implantações de produção enquanto responde a uma pergunta sobre a configuração de testes locais. Ele pode alucinar etapas de um checklist de release em uma simples correção de bug. Cada parágrafo extra de texto não relacionado é uma distração prestes a acontecer.
A matemática é direta. A maioria dos turnos não precisa da maioria das skills. Se você está pedindo uma correção rápida para um log de erro, você não precisa do texto completo de um runbook de implantação ou de um guia de hardening de segurança. Você precisa que o modelo veja o erro, entenda as convenções do seu projeto e edite o arquivo correto. Carregar corpos de skills irrelevantes não ajuda o modelo a fazer isso. Isso força o modelo a filtrar dados inúteis antes mesmo de começar a trabalhar no seu problema real.
Como Funciona o Carregamento sob Demanda
O mecanismo é simples, mas deliberado. O APC continua a manter a fonte da verdade. Suas definições de skills permanecem onde devem estar: em .apc/skills/<name>.md.
O APX não espelha esses arquivos na memória ativa. Em vez disso, ele compila um registro compacto de nomes de skills. O modelo vê essa lista e entende que um catálogo existe. Se ele precisar navegar ou confirmar quais capacidades estão disponíveis, ele pode invocar uma chamada list_skills. Isso lhe dá visibilidade sem volume.
Quando a tarefa realmente exige a sintaxe exata, os passos detalhados ou as restrições específicas codificadas em um arquivo de skill, o modelo chama load_skill. Nesse momento, e apenas nesse momento, o APX busca o corpo Markdown completo do APC e o injeta no contexto. A instrução chega "quente", usada uma única vez para o seu propósito pretendido, e o sistema evita carregá-la como um peso morto.
Pense na diferença entre importar uma biblioteca e colar cada definição de função no seu arquivo principal. Uma abordagem mantém seu código navegável. A outra cria uma bagunça que só compila por acidente.
Quem Vence Quando as Skills Colidem
O APX também impõe uma ordem de prioridade clara quando carrega as skills. Nem todo ambiente é igual, e conselhos genéricos nunca devem sobrepor o conhecimento local.
As habilidades do projeto têm a prioridade máxima