Skill Bodies Should Load on Demand

A good skill system has two jobs that pull in opposite directions.

First, the project needs durable instructions that live in version control. That is APC's job. A project can keep reusable skill files under .apc/skills/, and agents can reference those skills by name from AGENTS.md or .apc/agents/<slug>.md.

Second, the runtime needs to stay fast and focused during actual work. That is APX's job. If every skill body is injected into every turn, the prompt gets noisy, token costs rise, and the model starts seeing instructions that do not matter for the current request.

That is why APX is right to treat skill bodies as on-demand runtime material rather than permanent prompt baggage.

In APC, the skill file is the project-owned source. The spec keeps this simple: skills are reusable instruction files under .apc/skills/<name>.md, meant to avoid repeating the same operational guidance across many agents. That keeps the durable contract in the repo, reviewable like any other project artifact.

But APX does not have to dump that whole contract into the model on every turn.

The runtime code is explicit about this tradeoff. In src/core/agent/skills/catalog.js, APX builds a compact skills hint block that lists only slugs. It tells the model that bodies are not loaded, that it can call list_skills to browse one-line descriptions, and load_skill({slug}) to fetch the full body when exact syntax is needed. That is a better default than preloading everything.

Why? Because most turns do not need most skills.

If a user asks for a quick summary, a design opinion, or a small code fix, loading a release checklist, a deployment runbook, a security review guide, and a migration playbook all at once just burns attention. The model now has to separate relevant instructions from irrelevant ones before it can even start solving the task.

APX also keeps the loading order practical. In src/core/agent/skills/loader.js, project skills shadow global ones, and global skills shadow built-in runtime skills. So APC keeps ownership of project-specific behavior, while APX still provides a safe fallback catalog. That split matters: portable context stays in the repo, but runtime convenience does not get mistaken for project truth.

There is an even stronger version of the same idea in APX's optional Skill Inspector. When enabled, the runtime suppresses the static slug dump and re-evaluates the current prompt each turn. High-confidence matches can inline one skill body. Lower-confidence matches become hints. Everything else stays out. The point is not magic retrieval. The point is prompt discipline.

This is the deeper APC/APX boundary:

• APC should preserve reusable knowledge.
• APX should decide how much of that knowledge becomes active for this turn.

A concrete example makes the split clearer.

Imagine a repo with these skills:

• release-checklist
• security-review
• support-triage
• docs-style

Those files belong in .apc/skills/ because they are durable project instructions. But if the user asks, "Explain this error log and suggest the smallest patch," APX should not inject all four bodies. A small hint that those skills exist is enough. Only if the turn becomes a release task or a security audit should the runtime pay to load the matching body.

That behavior keeps APC portable and APX usable.

Portable context is not the same as always-active context. A project can own many valid instructions without forcing every runtime turn to carry all of them. Once you accept that distinction, the architecture gets cleaner: APC stores the skill files, APX routes them into the prompt only when the request actually needs them.

That is the right default for daily agent work.