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.
प्रोजेक्ट स्किल्स (Project skills) को सर्वोच्च प्राथमिकता दी जाती है। ये फ़ाइलें आपके वर्तमान रिपॉजिटरी में .apc/skills/ के अंतर्गत रहती हैं। ये आपकी टीम के विशिष्ट कन्वेंशन (conventions), आपके कस्टम रैपर्स (custom wrappers), आपके पुराने नामकरण मानकों (legacy naming standards) और आपके विशेष टूलचेन (toolchain) को कैप्चर करती हैं। यदि आपका प्रोजेक्ट डेटाबेस माइग्रेशन को संभालने का अपना तरीका परिभाषित करता है, तो वह परिभाषा मान्य होगी।
इसके बाद ग्लोबल स्किल्स (Global skills) आती हैं। ये संगठन-व्यापी पैटर्न को कवर करती हैं जो तब लागू होते हैं जब प्रोजेक्ट स्वयं कुछ निर्दिष्ट नहीं करता है। ये एक स्टैंडर्ड लाइब्रेरी की तरह काम करती हैं।
बिल्ट-इन रनटाइम स्किल्स (Built-in runtime skills) सबसे नीचे फॉलबैक (fallback) के रूप में रहती हैं। ये उन सामान्य क्षमताओं को संभालती हैं जिन्हें हर एजेंट को समझना चाहिए, लेकिन किसी विशिष्ट प्रोजेक्ट ने उन्हें फिर से परिभाषित करने की आवश्यकता नहीं समझी है।
इस लेयर्ड अप्रोच (layered approach) का अर्थ है कि आपकी रिपॉजिटरी अपने स्वयं के व्यवहार पर नियंत्रण रखती है। कोई ग्लोबल या बिल्ट-इन स्किल गलती से उस वर्कफ़्लो को हाईजैक नहीं कर सकती जिसे आपकी टीम ने जानबूझकर कस्टमाइज़ किया है।
व्यवहार में यह कैसा दिखता है
एक सामान्य मेंटेनेंस टास्क की कल्पना करें। एक टीम का सदस्य चैट में एक एरर लॉग पेस्ट करता है। ट्रेसबैक (traceback) एक यूटिलिटी मॉड्यूल में एक सिंगल नल रेफरेंस (null reference) की ओर इशारा करता है। इसका समाधान संभवतः डिफेंसिव कोडिंग (defensive coding) की दो लाइनें हैं।
ऑन-डिमांड लोडिंग (on-demand loading) के बिना किसी सिस्टम में, APX कॉन्टेक्स्ट को उन सभी स्किल्स से भर देगा जिन्हें वह जानता है। अब मॉडल के पास उन दो लाइनों को छूने से पहले विचार करने के लिए चालीस पेज का टेक्स्ट है। वह रिलीज़ चेकलिस्ट (release checklist) देखता है और सोचता है कि क्या उसे वर्ज़न बढ़ाना चाहिए। वह सुरक्षा गाइड (security guide) देखता है और उस फंक्शन पर इनपुट वैलिडेशन (input validation) के बारे में सोचने लगता है जिसे केवल नल चेक (null check) की आवश्यकता है। वह डिप्लॉयमेंट रनबुक (deployment runbook) देखता है और स्टेजिंग एनवायरनमेंट (staging environments) के बारे में सोचने लगता है। मॉडल भटक जाता है। जवाब देने में अधिक समय लगता है। टोकन मीटर तेज़ी से घूमने लगता है।
APX के ऑन-डिमांड डिज़ाइन के साथ, मॉडल केवल नाम देखता है। वह जानता है कि [release-checklist], [security-guide], [deployment-runbook], और [error-handling] मौजूद हैं। वह पहले तीन को अनदेखा कर देता है। यदि आपके प्रोजेक्ट के नल सेफ्टी (null safety) के कन्वेंशन विशिष्ट हैं, तो वह [error-handling] को लोड कर सकता है। वह बग को ठीक कर देता है। असंबंधित स्किल्स कभी कॉन्टेक्स्ट विंडो (context window) में नहीं आईं। मॉडल केंद्रित रहा क्योंकि प्रॉम्प्ट (prompt) साफ रहा।
यही तर्क तब भी लागू होता है जब कार्य वास्तव में जटिल हो। यदि आप बाद में एजेंट को प्रोडक्शन डिप्लॉयमेंट (production deployment) तैयार करने के लिए कहते हैं, तो वह डिप्लॉयमेंट रनबुक लोड कर सकता है, सुरक्षा गाइड से परामर्श कर सकता है, और रिलीज़ चेकलिस्ट का ठीक उसी समय पालन कर सकता है जब वे चरण प्रासंगिक हो जाते हैं। ज्ञान हमेशा वहीं था। उसने बस सही समय का इंतज़ार किया।
आर्किटेक्चर के रूप में प्रॉम्प्ट डिसिप्लिन
APC और APX के बीच का अलगाव केवल एक कार्यान्वयन विवरण (implementation detail) नहीं है। यह प्रॉम्प्ट डिसिप्लिन का एक दर्शन है। APC ज्ञान को हमेशा के लिए सुरक्षित रखता है, जिससे इसे रिव्यू करने योग्य, वर्ज़न्ड और सुरक्षित बनाया जा सकता है। APX यह तय करता है कि उस ज्ञान का कितना हिस्सा अभी सक्रिय कॉन्टेक्स्ट (active context) में जगह पाने का हकदार है।
एक समृद्ध स्किल कैटलॉग (skill catalog) एक संपत्ति है। एक फूला हुआ (bloated) प्रॉम्प्ट एक देनदारी (liability) है। लक्ष्य आपके कॉन्टेक्स्ट को हमेशा सक्रिय बनाए बिना उसे पोर्टेबल रखना है। आपकी रिपॉजिटरी में वे सभी निर्देश होने चाहिए जो आपकी टीम ने कभी लिखे हैं, लेकिन एजेंट को केवल उन्हें ही पढ़ना चाहिए जो तत्काल कार्य में मदद करते हैं।
यदि आपका सिस्टम मॉडल को हर टर्न में हर स्किल की पूरी बॉडी ले जाने के लिए मजबूर करता है, तो आप एक इंटेलिजेंट असिस्टेंट नहीं बना रहे हैं। आप एक ऐसा लाइब्रेरियन बना रहे हैं जो हर रेफरेंस डेस्क प्रश्न के लिए पूरे आर्काइव को घसीट कर लाता है। सब कुछ स्टोर करें। जो महत्वपूर्ण है उसे लोड करें। इसी तरह आप एजेंटों को तेज़, कॉन्टेक्स्ट को साफ और तर्क (reasoning) को सटीक रख सकते हैं।