Descriptions Should Trigger Loading, Not Store Context

A short description field should help a runtime decide what to load. It should not become a hiding place for half the project.

That boundary matters in APC and APX.

APC is the portable context layer. It keeps the repo-owned contract in files like AGENTS.md, .apc/agents/<slug>.md, and .apc/skills/<slug>/SKILL.md. APX is the daily-use runtime and tooling layer. It reads that contract, builds prompts, chooses which skill bodies to load, and keeps runtime state local.

Once you accept that split, the rule gets simple: descriptions are routing hints. Durable context belongs somewhere else.

Why the distinction matters

The APC companion spec for AGENTS.md defines Description as a one-line agent summary. That already points in the right direction. It is an index field, not a memory dump.

The APC apc-context skill makes the same design intent even clearer when it says description should exist for semantic activation.

APX then turns that design into runtime behavior.

In the apx-skill-builder skill, the rule is explicit: a skill description is what the model sees when deciding whether to call load_skill, so it should be written as the trigger condition, not as a body summary. In the apx-agent skill, the rule is just as direct: do not put long-running context in Description; put it in memory.md.

That is the clean APC/APX contract in miniature:

• APC stores the durable artifact.
• APX uses the short description to decide whether the artifact should become active for this turn.

What goes in each place

If a detail helps a model recognize when to use an agent or skill, it belongs in the short description.

If a detail explains how the agent should behave over time, or preserves durable project facts, it belongs in the body or memory.

That means:

• agent Description should name responsibility and trigger language
• skill frontmatter description should say when to load it
• agent memory should hold lasting context that should survive many turns
• skill bodies should hold the real instructions, examples, and gotchas

The mistake is to collapse all four jobs into one field.

A practical example

Suppose a project has a skill for MCP setup.

Bad description:

description: This skill describes APX's MCP system.

That tells APX almost nothing about when to load it.

Better description:

description: Register and debug an MCP server in APX. Load before running `apx mcp add` or `apx mcp check`; covers scopes, stdio gotchas, and secrets handling.

Now the field does real work. It gives the runtime trigger phrases, command names, and the decision boundary.

The same pattern applies to agents.

Weak agent description:

- **Description**: Senior engineer with broad experience across many domains and a strong focus on quality.

That sounds nice to a human, but it is vague as a runtime hint.

Stronger description:

- **Description**: Reviews pull requests, test risk, and migration hazards; use for regressions, missing coverage, and risky diffs.

That helps APX compose a clearer prompt, and it helps other tools discover the right agent without reading a giant blob first.

Why this keeps APC portable

When teams stuff too much into descriptions, portable context gets noisy fast.

The repo starts carrying mini-prompts in fields that should stay indexable. Diff quality drops. Discovery gets worse. Two tools may parse the same project but surface different behavior because the description stopped being a clean summary and became an overloaded instruction bucket.

Short trigger-oriented descriptions avoid that.

They keep APC files readable in Git, portable across tools, and easy to regenerate or normalize.

Why this keeps APX efficient

APX works best when it does not preload every heavy instruction block on every turn.

That is why short trigger text matters. APX can scan the small semantic surface first, then load the matching skill body or memory only when the task actually needs it. Less prompt noise. Better routing. Smaller context.

So the rule is not cosmetic. It is operational.

Use descriptions to answer: "When should this become active?"
Use memory and skill bodies to answer: "What should it do once active?"

That keeps APC small and portable, while APX stays precise in daily use.