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.
Kemahiran projek (Project skills) diberi keutamaan tertinggi. Fail-fail ini berada dalam repositori semasa anda di bawah .apc/skills/. Ia merangkumi konvensyen khusus pasukan anda, pembungkus (wrappers) tersuai anda, piawaian penamaan lama anda, dan rantaian alatan (toolchain) khusus anda. Jika projek anda menentukan caranya sendiri untuk mengendalikan migrasi pangkalan data, definisi tersebut akan diutamakan.
Kemahiran global (Global skills) menyusul selepas itu. Ini merangkumi corak di seluruh organisasi yang terpakai apabila projek itu sendiri tidak menetapkan apa-apa. Ia bertindak sebagai perpustakaan standard.
Kemahiran masa larian terbina dalam (Built-in runtime skills) berada di kedudukan paling bawah sebagai sandaran (fallback). Ia mengendalikan keupayaan generik yang sepatutnya difahami oleh setiap ejen tetapi tidak didefinisikan semula oleh mana-mana projek khusus.
Pendekatan berlapis ini bermakna repositori anda mengekalkan kawalan ke atas tingkah lakunya sendiri. Kemahiran global atau terbina dalam tidak boleh secara tidak sengaja merampas aliran kerja yang telah disesuaikan secara sengaja oleh pasukan anda.
Bagaimana Ia Berfungsi dalam Praktik
Bayangkan satu tugas penyelenggaraan biasa. Seorang rakan sepasukan menampal log ralat ke dalam sembang. Jejak ralat (traceback) menunjukkan rujukan null tunggal dalam modul utiliti. Pembaikannya berkemungkinan hanya dua baris pengekodan defensif.
Dalam sistem tanpa pemuatan atas permintaan (on-demand loading), APX akan memenuhkan konteks dengan setiap kemahiran yang diketahui. Model kini mempunyai empat puluh halaman teks untuk dipertimbangkan sebelum menyentuh dua baris tersebut. Ia melihat senarai semak pelancaran (release checklist) dan tertanya-tanya jika ia perlu menaik taraf versi. Ia melihat panduan keselamatan dan mempertimbangkan pengesahan input pada fungsi yang hanya memerlukan semakan null. Ia melihat buku panduan penggunaan (deployment runbook) dan mula berfikir tentang persekitaran pementasan (staging environments). Model tersebut mula terpesong. Respons mengambil masa lebih lama. Meter token berpusing laju.
Dengan reka bentuk atas permintaan APX, model hanya melihat nama-namanya sahaja. Ia tahu bahawa [release-checklist], [security-guide], [deployment-runbook], dan [error-handling] wujud. Ia mengabaikan tiga yang pertama. Ia mungkin memuatkan [error-handling] jika konvensyen projek anda untuk keselamatan null adalah khusus. Ia membaiki pepijat tersebut. Kemahiran yang tidak berkaitan tidak pernah memasuki tetingkap konteks. Model kekal fokus kerana prompt kekal bersih.
Logik yang sama terpakai apabila tugasan tersebut sebenarnya kompleks. Jika anda kemudian meminta ejen untuk menyediakan penggunaan pengeluaran (production deployment), ia boleh memuatkan buku panduan penggunaan, merujuk panduan keselamatan, dan mengikut senarai semak pelancaran tepat pada masanya apabila langkah-langkah tersebut menjadi relevan. Pengetahuan itu sentiasa ada. Ia hanya menunggu masa yang sesuai.
Disiplin Prompt sebagai Seni Bina
Pemisahan antara APC dan APX bukan sekadar butiran pelaksanaan. Ia adalah satu falsafah disiplin prompt. APC memelihara pengetahuan selama-lamanya, menjadikannya boleh disemak, mempunyai versi, dan selamat. APX memutuskan sejauh mana pengetahuan tersebut layak mendapat tempat dalam konteks aktif sekarang.
Katalog kemahiran yang kaya adalah satu aset. Prompt yang terlalu sarat adalah satu liabiliti. Matlamatnya adalah untuk memastikan konteks anda mudah alih tanpa menjadikannya sentiasa aktif. Repositori anda harus mengandungi setiap arahan yang pernah ditulis oleh pasukan anda, tetapi ejen hanya perlu membaca arahan yang membantu tugasan segera sahaja.
Jika sistem anda memaksa model untuk membawa setiap kandungan kemahiran ke dalam setiap pusingan, anda bukan sedang membina pembantu pintar. Anda sedang membina seorang pustakawan yang mengheret seluruh arkib ke setiap meja pertanyaan rujukan. Simpan segalanya. Muat apa yang penting. Begitulah cara anda memastikan ejen pantas, konteks bersih, dan penaakulan tajam.