Every agent system faces the same uncomfortable trade-off. You want a deep, well-organized knowledge base that survives code reviews and git history. But you also need the runtime to move fast and stay focused. These two needs work against each other. The more instructions you preserve, the more tempting it becomes to dump all of them into the prompt and hope for the best. That hope is expensive.
In the Agent Project Context ecosystem, this tension splits cleanly across two layers. APC handles durability. APX handles speed. Understanding how they interact—and why APX refuses to preload every skill definition—reveals more about prompt engineering than most optimization guides will tell you.
The Archive and the Engine
APC’s job is permanence. It stores reusable skill files under .apc/skills/ as plain Markdown documents. Because these files live inside your repository, they ride along with version control. You can open a pull request that changes a deployment procedure. You can diff a security policy rollback from six weeks ago. You can audit exactly what the agent was supposed to know and when. That reviewability matters when a bad deployment goes live or a compliance auditor starts asking questions.
APX, on the other hand, lives in the moment. It manages the actual conversation between you and the model. Its goal is not to archive knowledge but to use it precisely. When APX treats skills as permanent baggage, the whole system slows down. The context window fills up. Token costs climb. Worse, the model’s attention scatters across instructions that have nothing to do with the current request.
This is why skill bodies load on demand.
The True Cost of a Bloated Prompt
Most teams understand that tokens cost money. Fewer teams appreciate that irrelevant tokens cost accuracy.
When APX injects every available skill into every turn, the prompt turns noisy. The model receives the deployment runbook, the security guide, the API style reference, the testing checklist, and the onboarding FAQ all at once. Even with a large context window, reasoning quality degrades when the model must first sift through noise to find signal. It might latch onto a security requirement meant for production deployments while answering a question about local test setup. It might hallucinate steps from a release checklist into a simple bug fix. Every extra paragraph of unrelated text is a distraction waiting to happen.
The math is straightforward. Most turns do not need most skills. If you are asking for a quick fix to an error log, you do not need the full text of a deployment runbook or a security hardening guide. You need the model to see the error, understand your project conventions, and edit the right file. Loading irrelevant skill bodies does not help the model do this. It forces the model to filter out useless data before it even starts working on your actual problem.
How On-Demand Loading Works
The mechanism is simple but deliberate. APC continues to hold the ground truth. Your skill definitions remain where they belong: in .apc/skills/<name>.md.
APX does not mirror those files into active memory. Instead, it compiles a compact registry of skill names. The model sees this list and understands that a catalog exists. If it needs to browse or confirm what capabilities are available, it can invoke a list_skills call. This gives it visibility without volume.
When the task actually requires the exact syntax, the detailed steps, or the specific constraints encoded in a skill file, the model calls load_skill. At that point, and only that point, APX fetches the full Markdown body from APC and injects it into the context. The instruction arrives hot, used once for its intended purpose, and the system avoids carrying it around as dead weight.
Think of the difference between importing a library and pasting every function definition into your main file. One approach keeps your codebase navigable. The other creates a mess that only compiles by accident.
Who Wins When Skills Collide
APX also enforces a clear priority order when it does load skills. Not every environment is the same, and generic advice should never override local knowledge.
Le skill di progetto hanno la massima priorità. Questi file risiedono nel repository corrente sotto .apc/skills/. Catturano le convenzioni specifiche del tuo team, i tuoi wrapper personalizzati, i tuoi standard di denominazione legacy e la tua particolare toolchain. Se il tuo progetto definisce il proprio modo di gestire le migrazioni del database, quella definizione prevale.
Le skill globali vengono subito dopo. Queste coprono pattern a livello organizzativo che si applicano quando il progetto stesso non fornisce istruzioni. Fungono da libreria standard.
Le skill di runtime integrate si trovano alla base come fallback. Gestiscono capacità generiche che ogni agente dovrebbe comprendere, ma che nessun progetto specifico si è preso la briga di ridefinire.
Questo approccio a livelli significa che il tuo repository mantiene il controllo sul proprio comportamento. Una skill globale o integrata non può dirottare accidentalmente un workflow che il tuo team ha intenzionalmente personalizzato.
Cosa significa questo in pratica
Immagina un tipico compito di manutenzione. Un collega incolla un log di errore nella chat. Il traceback punta a un singolo riferimento nullo in un modulo di utilità. La correzione consiste probabilmente in due righe di coding difensivo.
In un sistema senza caricamento on-demand, APX riempirebbe il contesto con ogni skill che conosce. Il modello si ritroverebbe con quaranta pagine di testo da considerare prima di toccare quelle due righe. Vede la checklist di rilascio e si chiede se debba incrementare una versione. Vede la guida alla sicurezza e contempla la validazione dell'input su una funzione che necessita solo di un controllo null. Vede il runbook di deployment e inizia a pensare agli ambienti di staging. Il modello perde il focus. La risposta richiede più tempo. Il contatore dei token accelera.
Grazie al design on-demand di APX, il modello vede solo i nomi. Sa che [release-checklist], [security-guide], [deployment-runbook] e [error-handling] esistono. Ignora i primi tre. Potrebbe caricare [error-handling] se le convenzioni del tuo progetto per la null safety sono specifiche. Corregge il bug. Le skill non correlate non sono mai entrate nella finestra di contesto. Il modello è rimasto concentrato perché il prompt è rimasto pulito.
La stessa logica vale quando il compito è effettivamente complesso. Se in seguito chiedi all'agente di preparare un deployment in produzione, esso potrà caricare il runbook di deployment, consultare la guida alla sicurezza e seguire la checklist di rilascio esattamente quando questi passaggi diventano rilevanti. La conoscenza era sempre lì. Ha semplicemente aspettato il momento giusto.
La disciplina del prompt come architettura
La separazione tra APC e APX non è solo un dettaglio di implementazione. È una filosofia di disciplina del prompt. APC preserva la conoscenza per sempre, rendendola revisionabile, versionata e sicura. APX decide quanta di quella conoscenza meriti un posto nel contesto attivo in questo momento.
Un catalogo di skill ricco è un asset. Un prompt sovraccarico è un rischio. L'obiettivo è mantenere il contesto portabile senza renderlo sempre attivo. Il tuo repository dovrebbe contenere ogni istruzione che il tuo team abbia mai scritto, ma l'agente dovrebbe leggere solo quelle che aiutano con il compito immediato.
Se il tuo sistema costringe il modello a trasportare il corpo di ogni skill in ogni turno, non stai costruendo un assistente intelligente. Stai costruendo un bibliotecario che trascina l'intero archivio a ogni domanda allo sportello. Salva tutto. Carica ciò che conta. È così che mantieni gli agenti veloci, il contesto pulito e il ragionamento acuto.