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 take the top priority. These files live in your current repository under .apc/skills/. They capture your team’s specific conventions, your custom wrappers, your legacy naming standards, and your particular toolchain. If your project defines its own way of handling database migrations, that definition wins.
Global skills come next. These cover organization-wide patterns that apply when the project itself stays silent. They act as a standard library.
Built-in runtime skills sit at the bottom as the fallback. They handle generic capabilities that every agent should understand but that no specific project has bothered to redefine.
This layered approach means your repository keeps control over its own behavior. A global or built-in skill cannot accidentally hijack a workflow that your team has intentionally customized.
What This Looks Like in Practice
Picture a typical maintenance task. A teammate pastes an error log into the chat. The traceback points to a single null reference in a utility module. The fix is likely two lines of defensive coding.
In a system without on-demand loading, APX would stuff the context with every skill it knows. The model now has forty pages of text to consider before touching those two lines. It sees the release checklist and wonders if it should bump a version. It sees the security guide and contemplates input validation on a function that just needs a null check. It sees the deployment runbook and starts thinking about staging environments. The model drifts. The response takes longer. The token meter spins.
With APX’s on-demand design, the model sees only the names. It knows that [release-checklist], [security-guide], [deployment-runbook], and [error-handling] exist. It ignores the first three. It might load [error-handling] if your project’s conventions for null safety are specific. It fixes the bug. The unrelated skills never entered the context window. The model stayed focused because the prompt stayed clean.
The same logic holds when the task actually is complex. If you later ask the agent to prepare a production deployment, it can load the deployment runbook, consult the security guide, and follow the release checklist exactly when those steps become relevant. The knowledge was always there. It simply waited for the right moment.
Prompt Discipline as Architecture
The separation between APC and APX is not just an implementation detail. It is a philosophy of prompt discipline. APC preserves knowledge forever, making it reviewable, versioned, and safe. APX decides how much of that knowledge earns a place in the active context right now.
A rich skill catalog is an asset. A bloated prompt is a liability. The goal is to keep your context portable without making it always active. Your repository should contain every instruction your team has ever written, but the agent should read only the ones that help with the immediate task.
If your system forces the model to carry every skill body into every turn, you are not building an intelligent assistant. You are building a librarian who drags the entire archive to every reference desk question. Store everything. Load what matters. That is how you keep agents fast, context clean, and reasoning sharp.