Every agent system faces the same uncomfortable trade off. You want a deep, well organized knowledge base that survives

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.

Proje becerileri en yüksek önceliğe sahiptir. Bu dosyalar, mevcut deponuzda .apc/skills/ altında bulunur. Ekibinizin özel kurallarını, özel sarmalayıcılarını (wrappers), eski isimlendirme standartlarını ve size özgü araç zincirinizi (toolchain) kapsarlar. Eğer projeniz veritabanı göçlerini (migrations) yönetmek için kendi yöntemini tanımlıyorsa, o tanım geçerli olur.

Sırada küresel beceriler gelir. Bunlar, projenin kendisi sessiz kaldığında uygulanan, organizasyon genelindeki kalıpları kapsar. Standart bir kütüphane görevi görürler.

Yerleşik çalışma zamanı (runtime) becerileri ise en altta yedek (fallback) olarak yer alır. Her ajanın anlaması gereken ancak hiçbir özel projenin yeniden tanımlamaya gerek duymadığı genel yetenekleri yönetirler.

Bu katmanlı yaklaşım, deponuzun kendi davranışı üzerinde kontrol sahibi olduğu anlamına gelir. Küresel veya yerleşik bir beceri, ekibinizin kasıtlı olarak özelleştirdiği bir iş akışını yanlışlıkla ele geçiremez.

Bunun Pratikteki Görünümü

Tipik bir bakım görevini hayal edin. Bir ekip arkadaşınız sohbet kısmına bir hata günlüğü (error log) yapıştırır. Hata izleme (traceback), bir yardımcı modüldeki tek bir null referansına işaret eder. Çözüm muhtemelen iki satırlık savunmacı kodlamadır (defensive coding).

İsteğe bağlı yükleme (on-demand loading) özelliği olmayan bir sistemde APX, bağlamı (context) bildiği her beceriyle doldururdu. Modelin o iki satıra dokunmadan önce değerlendirmesi gereken kırk sayfalık bir metni olurdu. Sürüm kontrol listesini (release checklist) görür ve bir sürümü yükseltip yükseltmemesi gerektiğini merak eder. Güvenlik kılavuzunu görür ve sadece bir null kontrolüne ihtiyaç duyan bir fonksiyon üzerinde girdi doğrulaması (input validation) yapmayı düşünür. Dağıtım kılavuzunu (deployment runbook) görür ve hazırlık ortamları (staging environments) hakkında düşünmeye başlar. Model odağını kaybeder. Yanıt daha uzun sürer. Token sayacı hızla döner.

APX'in isteğe bağlı tasarımı sayesinde model sadece isimleri görür. [release-checklist], [security-guide], [deployment-runbook] ve [error-handling] öğelerinin mevcut olduğunu bilir. İlk üçünü görmezden gelir. Eğer projenizin null güvenliği (null safety) kuralları özelse, [error-handling] öğesini yükleyebilir. Hatayı düzeltir. İlgisiz beceriler bağlam penceresine (context window) hiç girmez. Komut (prompt) temiz kaldığı için model odaklanmış kalır.

Aynı mantık görev gerçekten karmaşık olduğunda da geçerlidir. Eğer daha sonra ajandan bir üretim dağıtımı (production deployment) hazırlamasını isterseniz, bu adımlar ilgili hale geldiğinde dağıtım kılavuzunu yükleyebilir, güvenlik kılavuzuna danışabilir ve sürüm kontrol listesini tam olarak takip edebilir. Bilgi her zaman oradaydı; sadece doğru anı bekledi.

Mimari Olarak Komut Disiplini

APC ve APX arasındaki ayrım sadece bir uygulama detayı değildir. Bu, bir komut disiplini felsefesidir. APC bilgiyi sonsuza dek korur; onu incelenebilir, versiyonlanmış ve güvenli hale getirir. APX ise bu bilginin ne kadarının şu anda aktif bağlamda yer almayı hak ettiğine karar verir.

Zengin bir beceri kataloğu bir varlıktır. Şişkin bir komut (prompt) ise bir yükümlülüktür. Amaç, bağlamı her zaman aktif hale getirmeden taşınabilir tutmaktır. Deponuz ekibinizin şimdiye kadar yazdığı her talimatı içermelidir, ancak ajan yalnızca o anki göreve yardımcı olanları okumalıdır.

Eğer sisteminiz modeli her adımda her beceri içeriğini taşımaya zorluyorsa, akıllı bir asistan inşa etmiyorsunuz demektir. Her referans masası sorusu için tüm arşivi sürükleyip getiren bir kütüphaneci inşa ediyorsunuzdur. Her şeyi saklayın. Önemli olanı yükleyin. Ajanları hızlı, bağlamı temiz ve muhakemeyi keskin tutmanın yolu budur.